Prototype: add Shopify CLI agent conversation context

[dmerand]

WHY are these changes introduced?

This is an exploratory prototype for moving broader agent conversation bookkeeping into Shopify CLI instead of requiring every harness to rebuild the full SHOPIFY_CLI_AGENT* payload on every command.

The main question behind the prototype is:

• can Shopify CLI mint and persist a conversation-scoped agent context once,
• let later commands reuse that handle,
• and still emit analytics through the existing Monorail path?

This PR is meant to demonstrate the integration shape, not to claim the API is final.

WHAT is this pull request doing?

Prototype changes:

• add a new cli-kit helper for agent conversation context:
  • generate conversation IDs (conv_<uuid>)
  • create / inspect / end a temp-file-backed conversation context
  • expand SHOPIFY_CLI_AGENT_CONTEXT into effective SHOPIFY_CLI_AGENT* env vars
• add prototype CLI commands:
  • shopify agent conversation start
  • shopify agent conversation inspect
  • shopify agent conversation end
• keep the current analytics emission path unchanged at the Monorail boundary:
  • analytics still emits env_shopify_variables
  • the prototype just teaches CLI how to resolve a conversation context handle into that payload
• add focused tests around the helper, analytics expansion, and the new commands

Important non-goals for this prototype:

• not a final public contract
• not a decision that all agent metadata should remain in env_shopify_variables
• not a decision against extracting the ID/context logic into a smaller reusable package for non-CLI flows

Example prompt → CLI execution flow

One possible future flow this prototype is trying to enable:

User prompt to an agent

Validate my shopify.app.toml from the app root.

Agent / harness starts one broader CLI conversation for the session

shopify agent conversation start \
  --conversation-id "$CONVERSATION_ID" \
  --agent pi \
  --agent-version 0.70.2 \
  --provider shopify \
  --harness pi \
  --model gpt-5 \
  --json

Example JSON response:

{
  "conversationId": "conv_123",
  "contextPath": "/tmp/tmp-abc123/shopify-agent-conversation.json",
  "agent": "pi",
  "agentVersion": "0.70.2",
  "provider": "shopify",
  "harness": "pi",
  "model": "gpt-5",
  "startedAt": "2026-05-04T16:00:00.000Z"
}

Agent executes one or more Shopify CLI commands during that conversation

SHOPIFY_CLI_AGENT_CONTEXT=/tmp/tmp-abc123/shopify-agent-conversation.json \
SHOPIFY_CLI_AGENT_RUN_ID=run_001 \
shopify app config validate --json

A later command in the same broader conversation would reuse the same context path and only change the run ID as needed:

SHOPIFY_CLI_AGENT_CONTEXT=/tmp/tmp-abc123/shopify-agent-conversation.json \
SHOPIFY_CLI_AGENT_RUN_ID=run_002 \
shopify version

Agent can inspect or end the conversation explicitly

shopify agent conversation inspect --json
shopify agent conversation end --json

That gives the host a CLI-owned conversation handle while keeping per-run boundaries explicit.

How to test your changes?

Focused checks used for the prototype:

pnpm --filter @shopify/cli-kit vitest run src/public/node/agent.test.ts src/public/node/analytics.test.ts
pnpm --filter @shopify/cli vitest run src/cli/commands/agent/conversation/start.test.ts src/cli/commands/agent/conversation/inspect.test.ts src/cli/commands/agent/conversation/end.test.ts
pnpm --filter @shopify/cli-kit type-check

Optional manual sanity check:

shopify agent conversation start --agent pi --provider shopify --model gpt-5 --json
SHOPIFY_CLI_AGENT_CONTEXT=<contextPath from start> SHOPIFY_CLI_AGENT_RUN_ID=run_123 shopify version
shopify agent conversation inspect --json
shopify agent conversation end --json

Post-release steps

None. This is exploratory prototype work.

Exploration notes / open questions

• Should the conversation ID / context helpers live in an extractable library so web / MCP-only flows can reuse the same logic without shelling out to CLI?
• Should any of agent, provider, model, harness, or conversation_id graduate to first-class Monorail fields instead of staying inside env_shopify_variables?
• Is the right UX actually shopify agent conversation ..., or should CLI expose a thinner helper surface?

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• The change is user-facing — I've identified the correct bump type (patch) and added a changeset with pnpm changeset add

[dmerand]

• Prototype: add Shopify CLI agent conversation context #7460 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

packages/cli-kit/dist/public/node/agent.d.ts

export declare const SHOPIFY_CLI_AGENT_CONTEXT = "SHOPIFY_CLI_AGENT_CONTEXT";
export declare const SHOPIFY_CLI_AGENT = "SHOPIFY_CLI_AGENT";
export declare const SHOPIFY_CLI_AGENT_VERSION = "SHOPIFY_CLI_AGENT_VERSION";
export declare const SHOPIFY_CLI_AGENT_PROVIDER = "SHOPIFY_CLI_AGENT_PROVIDER";
export declare const SHOPIFY_CLI_AGENT_MODEL = "SHOPIFY_CLI_AGENT_MODEL";
export declare const SHOPIFY_CLI_AGENT_HARNESS = "SHOPIFY_CLI_AGENT_HARNESS";
export declare const SHOPIFY_CLI_AGENT_RUN_ID = "SHOPIFY_CLI_AGENT_RUN_ID";
export declare const SHOPIFY_CLI_AGENT_SESSION_ID = "SHOPIFY_CLI_AGENT_SESSION_ID";
export interface AgentConversationContext {
    conversationId: string;
    agent?: string;
    agentVersion?: string;
    provider?: string;
    harness?: string;
    model?: string;
    startedAt: string;
}
export interface AgentConversationHandle extends AgentConversationContext {
    contextPath: string;
}
export interface StartAgentConversationInput {
    conversationId?: string;
    agent?: string;
    agentVersion?: string;
    provider?: string;
    harness?: string;
    model?: string;
    startedAt?: string;
}
export declare function generateConversationId(): string;
export declare function createAgentConversationContext(input?: StartAgentConversationInput): AgentConversationContext;
export declare function startAgentConversation(input?: StartAgentConversationInput): Promise<AgentConversationHandle>;
export declare function inspectAgentConversation(options?: {
    contextPath?: string;
    env?: NodeJS.ProcessEnv;
}): Promise<AgentConversationHandle>;
export declare function endAgentConversation(options?: {
    contextPath?: string;
    env?: NodeJS.ProcessEnv;
}): Promise<AgentConversationHandle>;
export declare function agentConversationEnvironmentVariables(conversation: AgentConversationContext, contextPath: string): Record<string, string>;
export declare function resolveShopifyAgentEnvironmentVariables(env?: NodeJS.ProcessEnv): Promise<Record<string, string>>;

Existing type declarations

We found no diffs with existing type declarations