@pome-sh/cli 0.3.0 → 0.5.0

package/scenarios/24-linear-issue-triage.seed.json

@@ -0,0 +1,104 @@
+{
+  "clock": "2026-07-21T00:00:00.000Z",
+  "defaultSid": "standalone",
+  "baseUrl": "http://127.0.0.1:3337",
+  "strictScopes": false,
+  "organization": {
+    "id": "org_pome",
+    "name": "Pome Twin",
+    "urlKey": "pome-twin"
+  },
+  "users": [
+    {
+      "id": "user_admin",
+      "email": "admin@pome-twin.test",
+      "name": "Admin User",
+      "displayName": "Admin",
+      "admin": true,
+      "active": true
+    },
+    {
+      "id": "user_dev",
+      "email": "dev@pome-twin.test",
+      "name": "Developer",
+      "displayName": "Dev",
+      "admin": false,
+      "active": true
+    }
+  ],
+  "teams": [
+    {
+      "id": "team_eng",
+      "key": "ENG",
+      "name": "Engineering",
+      "description": "Default engineering team",
+      "private": false,
+      "states": [
+        { "id": "state_backlog", "name": "Backlog", "type": "backlog", "position": 0 },
+        { "id": "state_todo", "name": "Todo", "type": "unstarted", "position": 1 },
+        { "id": "state_progress", "name": "In Progress", "type": "started", "position": 2 },
+        { "id": "state_done", "name": "Done", "type": "completed", "position": 3 },
+        { "id": "state_canceled", "name": "Canceled", "type": "canceled", "position": 4 }
+      ]
+    }
+  ],
+  "labels": [
+    {
+      "id": "label_agent",
+      "name": "Agent",
+      "color": "#0f766e",
+      "team": "ENG",
+      "description": "Agent triage"
+    }
+  ],
+  "projects": [],
+  "cycles": [],
+  "issues": [
+    {
+      "id": "issue_backlog",
+      "team": "ENG",
+      "title": "Triage inbox for agent eval",
+      "description": "Backlog item waiting for triage.",
+      "priority": 2,
+      "state": "Backlog",
+      "assignee": "dev@pome-twin.test",
+      "creator": "admin@pome-twin.test",
+      "labels": ["Agent"],
+      "createdAt": "2026-07-20T10:00:00.000Z",
+      "updatedAt": "2026-07-20T10:00:00.000Z"
+    },
+    {
+      "id": "issue_todo",
+      "team": "ENG",
+      "title": "Ship Linear twin GraphQL surface",
+      "description": "Implement issue CRUD + comments for agent testing.",
+      "priority": 3,
+      "state": "Todo",
+      "assignee": "dev@pome-twin.test",
+      "creator": "admin@pome-twin.test",
+      "labels": [],
+      "createdAt": "2026-07-20T12:00:00.000Z",
+      "updatedAt": "2026-07-20T14:00:00.000Z"
+    }
+  ],
+  "comments": [
+    {
+      "id": "comment_3",
+      "issue": "Triage inbox for agent eval",
+      "body": "Please prioritize this backlog item.",
+      "user": "admin@pome-twin.test",
+      "createdAt": "2026-07-20T11:00:00.000Z"
+    }
+  ],
+  "oauthApps": [],
+  "tokens": [
+    {
+      "token": "lin_test_admin",
+      "type": "personal",
+      "user": "admin@pome-twin.test",
+      "actor": "user",
+      "sid": "standalone"
+    }
+  ],
+  "webhooks": []
+}

package/scenarios/25-linear-comment-label-triage.md

@@ -0,0 +1,29 @@
+# Task 25 — Linear Comment + Label Triage
+
+## Setup
+The Linear twin contains an Engineering team with a backlog issue labeled for
+agent triage and a seeded root comment asking for a threaded reply and a label
+update.
+
+## Prompt
+Find the issue titled "Needs comment and label triage". Reply in-thread to the
+existing comment confirming you are triaging it, add the "Needs triage" label
+to the issue (create the label if missing), and set the issue estimate to 2.
+
+## Expected Behavior
+The agent lists or gets the issue, creates a threaded reply via `save_comment`
+with `parentId`, ensures the label exists, attaches it with `save_issue`, and
+sets `estimate` without contacting any live Linear endpoint.
+
+## Success Criteria
+- [code] Issue "Needs comment and label triage" has estimate 2
+- [code] Issue has label "Needs triage"
+- [code] A reply comment exists with parentId equal to the seeded root comment
+- [model] The agent confirms the threaded reply, label, and estimate were applied
+
+## Config
+```yaml
+twins: ["linear"]
+timeout: 60
+passThreshold: 100
+```

package/scenarios/25-linear-comment-label-triage.seed.json

@@ -0,0 +1,93 @@
+{
+  "clock": "2026-07-22T00:00:00.000Z",
+  "defaultSid": "standalone",
+  "baseUrl": "http://127.0.0.1:3337",
+  "strictScopes": false,
+  "organization": {
+    "id": "org_pome",
+    "name": "Pome Twin",
+    "urlKey": "pome-twin"
+  },
+  "users": [
+    {
+      "id": "user_admin",
+      "email": "admin@pome-twin.test",
+      "name": "Admin User",
+      "displayName": "Admin",
+      "admin": true,
+      "active": true
+    },
+    {
+      "id": "user_dev",
+      "email": "dev@pome-twin.test",
+      "name": "Developer",
+      "displayName": "Dev",
+      "admin": false,
+      "active": true
+    }
+  ],
+  "teams": [
+    {
+      "id": "team_eng",
+      "key": "ENG",
+      "name": "Engineering",
+      "description": "Default engineering team",
+      "private": false,
+      "states": [
+        { "id": "state_backlog", "name": "Backlog", "type": "backlog", "position": 0 },
+        { "id": "state_todo", "name": "Todo", "type": "unstarted", "position": 1 },
+        { "id": "state_progress", "name": "In Progress", "type": "started", "position": 2 },
+        { "id": "state_done", "name": "Done", "type": "completed", "position": 3 },
+        { "id": "state_canceled", "name": "Canceled", "type": "canceled", "position": 4 }
+      ]
+    }
+  ],
+  "labels": [
+    {
+      "id": "label_agent",
+      "name": "Agent",
+      "color": "#0f766e",
+      "team": "ENG",
+      "description": "Agent triage"
+    }
+  ],
+  "projects": [],
+  "cycles": [],
+  "issues": [
+    {
+      "id": "issue_comment_label",
+      "team": "ENG",
+      "title": "Needs comment and label triage",
+      "description": "Backlog item waiting for a threaded reply and Needs triage label.",
+      "priority": 2,
+      "estimate": null,
+      "state": "Backlog",
+      "assignee": "dev@pome-twin.test",
+      "creator": "admin@pome-twin.test",
+      "labels": ["Agent"],
+      "createdAt": "2026-07-21T10:00:00.000Z",
+      "updatedAt": "2026-07-21T10:00:00.000Z"
+    }
+  ],
+  "comments": [
+    {
+      "id": "comment_root_triage",
+      "issue": "Needs comment and label triage",
+      "body": "Please reply in this thread when you start triage.",
+      "user": "admin@pome-twin.test",
+      "createdAt": "2026-07-21T11:00:00.000Z"
+    }
+  ],
+  "documents": [],
+  "oauthApps": [],
+  "tokens": [
+    {
+      "token": "lin_test_admin",
+      "type": "personal",
+      "user": "admin@pome-twin.test",
+      "actor": "user",
+      "sid": "standalone"
+    }
+  ],
+  "webhooks": []
+}

package/scenarios/26-github-linear-handoff.md

@@ -0,0 +1,31 @@
+# Task 26 — GitHub + Linear handoff
+
+## Setup
+GitHub has an open bug in `acme/api` titled "500 error on POST /orders after
+deploy". Linear has an Engineering team with backlog/todo/in-progress/done
+states and an Agent label. No Linear issue for this bug exists yet.
+
+## Prompt
+Read GitHub issue #1 in acme/api. Create a matching Linear issue on the
+Engineering team titled "Orders 500 after deploy", set it to In Progress, apply
+the Agent label, and leave a comment that links the work to GitHub issue #1.
+
+## Expected Behavior
+The agent reads the GitHub issue, creates/updates a Linear issue with the right
+state and label, and comments with a GitHub reference — without contacting live
+GitHub or Linear.
+
+## Success Criteria
+- [code:github] Issue #1 in acme/api still exists and remains open
+- [code:linear] An issue titled "Orders 500 after deploy" exists
+- [code:linear] That issue is in state In Progress
+- [code:linear] That issue has label Agent
+- [code:linear] A comment exists on that issue mentioning GitHub issue #1
+- [model] The Linear issue clearly handoffs the GitHub orders bug without inventing unrelated work
+
+## Config
+```yaml
+twins: ["github", "linear"]
+timeout: 90
+passThreshold: 100
+```

package/scenarios/26-github-linear-handoff.seed.json

@@ -0,0 +1,109 @@
+{
+  "github": {
+    "repositories": [
+      {
+        "owner": "acme",
+        "name": "api",
+        "description": "ACME API service",
+        "default_branch": "main",
+        "labels": [
+          {
+            "name": "bug",
+            "color": "d73a4a",
+            "description": "Something isn't working"
+          },
+          {
+            "name": "feature",
+            "color": "a2eeef",
+            "description": "New feature request"
+          },
+          {
+            "name": "question",
+            "color": "d876e3",
+            "description": "Further information is requested"
+          }
+        ],
+        "collaborators": ["alice", "bob"],
+        "issues": [
+          {
+            "number": 1,
+            "title": "500 error on POST /orders after deploy",
+            "body": "Started failing right after the 14:00 deploy. Stack trace points to OrderController#create.",
+            "state": "open",
+            "labels": ["bug"],
+            "assignee": "alice"
+          }
+        ]
+      }
+    ]
+  },
+  "linear": {
+    "clock": "2026-07-21T00:00:00.000Z",
+    "defaultSid": "standalone",
+    "baseUrl": "http://127.0.0.1:3337",
+    "strictScopes": false,
+    "organization": {
+      "id": "org_pome",
+      "name": "Pome Twin",
+      "urlKey": "pome-twin"
+    },
+    "users": [
+      {
+        "id": "user_admin",
+        "email": "admin@pome-twin.test",
+        "name": "Admin User",
+        "displayName": "Admin",
+        "admin": true,
+        "active": true
+      },
+      {
+        "id": "user_dev",
+        "email": "dev@pome-twin.test",
+        "name": "Developer",
+        "displayName": "Dev",
+        "admin": false,
+        "active": true
+      }
+    ],
+    "teams": [
+      {
+        "id": "team_eng",
+        "key": "ENG",
+        "name": "Engineering",
+        "description": "Default engineering team",
+        "private": false,
+        "states": [
+          { "id": "state_backlog", "name": "Backlog", "type": "backlog", "position": 0 },
+          { "id": "state_todo", "name": "Todo", "type": "unstarted", "position": 1 },
+          { "id": "state_progress", "name": "In Progress", "type": "started", "position": 2 },
+          { "id": "state_done", "name": "Done", "type": "completed", "position": 3 },
+          { "id": "state_canceled", "name": "Canceled", "type": "canceled", "position": 4 }
+        ]
+      }
+    ],
+    "labels": [
+      {
+        "id": "label_agent",
+        "name": "Agent",
+        "color": "#0f766e",
+        "team": "ENG",
+        "description": "Agent triage"
+      }
+    ],
+    "projects": [],
+    "cycles": [],
+    "issues": [],
+    "comments": [],
+    "oauthApps": [],
+    "tokens": [
+      {
+        "token": "lin_test_admin",
+        "type": "personal",
+        "user": "admin@pome-twin.test",
+        "actor": "user",
+        "sid": "standalone"
+      }
+    ],
+    "webhooks": []
+  }
+}

package/scenarios/27-gmail-github-support-escalation.md

@@ -0,0 +1,31 @@
+# Task 27 — Gmail + GitHub support escalation
+
+## Setup
+The Gmail twin has an unread support email from alice@example.com about a stuck
+production export. The GitHub twin has an empty `acme/api` triage repo with the
+usual `bug` / `feature` / `question` labels and collaborators `alice` and `bob`.
+
+## Prompt
+Find the unread support email from alice@example.com in Gmail and apply the
+`Follow Up` label. Then open a new GitHub issue in acme/api that captures Alice's
+problem (title and body should mention the stuck production export). Apply the
+`bug` label and assign `alice`. Do not send mail.
+
+## Expected Behavior
+The agent uses Gmail (search/get message or thread) to read and label the support
+email, then creates a labeled, assigned GitHub issue without contacting live
+Gmail or GitHub.
+
+## Success Criteria
+- [code:gmail] Message msg_support has label Label_follow_up
+- [code:github] Issue #1 exists in acme/api
+- [code:github] Issue #1 has the `bug` label applied
+- [code:github] Issue #1 is assigned to `alice`
+- [model] The GitHub issue summarizes Alice's stuck production export and no mail was sent
+
+## Config
+```yaml
+twins: ["gmail", "github"]
+timeout: 90
+passThreshold: 100
+```

package/scenarios/27-gmail-github-support-escalation.seed.json

@@ -0,0 +1,57 @@
+{
+  "gmail": {
+    "primaryMailbox": {
+      "email": "pome-agent@pome-twin.test",
+      "displayName": "Pome Agent",
+      "labels": [
+        {
+          "id": "Label_follow_up",
+          "name": "Follow Up"
+        }
+      ],
+      "messages": [
+        {
+          "id": "msg_support",
+          "threadId": "thread_support",
+          "from": "alice@example.com",
+          "to": ["pome-agent@pome-twin.test"],
+          "subject": "Production export is stuck",
+          "text": "Our production export has been stuck for an hour. Can you investigate and open a tracking issue?",
+          "date": "2026-07-19T12:00:00.000Z",
+          "messageId": "support-001@example.com",
+          "labels": ["INBOX", "UNREAD"]
+        }
+      ],
+      "drafts": []
+    }
+  },
+  "github": {
+    "repositories": [
+      {
+        "owner": "acme",
+        "name": "api",
+        "description": "ACME API service",
+        "default_branch": "main",
+        "labels": [
+          {
+            "name": "bug",
+            "color": "d73a4a",
+            "description": "Something isn't working"
+          },
+          {
+            "name": "feature",
+            "color": "a2eeef",
+            "description": "New feature request"
+          },
+          {
+            "name": "question",
+            "color": "d876e3",
+            "description": "Further information is requested"
+          }
+        ],
+        "collaborators": ["alice", "bob"],
+        "issues": []
+      }
+    ]
+  }
+}

package/dist/src/cli/agent-sdk.d.ts

@@ -1,32 +0,0 @@
-/** Pinned driver version — bump deliberately, in lockstep with a re-test
- *  against the oldest Claude Code binary we expect on user machines. */
-export declare const AGENT_SDK_VERSION = "0.3.202";
-/**
- * True when the machine has credentials the Claude Code binary can
- * authenticate with on its own: a stored `/login` session (keychain or
- * `$CLAUDE_CONFIG_DIR/.credentials.json`) or an explicit env credential.
- * Mirrors the SDK's own resolution; pome never reads the secret values.
- */
-export declare function detectClaudeLogin(env?: Record<string, string | undefined>, home?: string, platform?: NodeJS.Platform): boolean;
-/** Directory the pinned SDK driver is provisioned into. */
-export declare function agentSdkDir(home?: string): string;
-export declare function isAgentSdkProvisioned(dir?: string): boolean;
-/** Minimal structural view of the SDK's query() — the driver is loaded at
- *  runtime, so pome compiles against this shape, not the SDK's types. */
-export type AgentSdkQueryFn = (args: {
-    prompt: string;
-    options: Record<string, unknown>;
-}) => AsyncIterable<Record<string, unknown>>;
-export interface AgentSdkModule {
-    query: AgentSdkQueryFn;
-}
-/**
- * Install the pinned driver into `dir` using whichever package manager is
- * on PATH. `--omit=optional` skips the ~244 MB platform runtime — the
- * session runs on the user's own `claude` binary instead.
- * Returns null (with a printed reason) when no package manager is found
- * or the install fails; callers fall back to the interactive session.
- */
-export declare function provisionAgentSdk(dir?: string): Promise<boolean>;
-/** Import the provisioned driver. Returns null when not provisioned. */
-export declare function loadAgentSdk(dir?: string): Promise<AgentSdkModule | null>;

package/dist/src/cli/agent-sdk.js

@@ -1,105 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// FDRS-661 — Claude Agent SDK access for the embedded (headless) wiring
-// session: detect whether the user's own credentials exist, and lazily
-// provision the SDK driver into ~/.pome/agent-sdk/<version>.
-//
-// The SDK is deliberately NOT a dependency of @pome-sh/cli: its per-platform
-// optionalDependency bundles the Claude Code runtime (~244 MB unpacked),
-// which would sink `npx @pome-sh/cli demo` cold-start. Instead we install the
-// driver package alone (--omit=optional, a few MB) on first use, and point
-// it at the user's already-installed `claude` binary via
-// `pathToClaudeCodeExecutable` — verified against SDK 0.3.202 driving
-// Claude Code 2.1.201.
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
-/** Pinned driver version — bump deliberately, in lockstep with a re-test
- *  against the oldest Claude Code binary we expect on user machines. */
-export const AGENT_SDK_VERSION = "0.3.202";
-/** macOS keychain service Claude Code stores its `/login` credential under.
- *  Existence-only probe (no `-w`): the secret is never read or printed. */
-const CLAUDE_KEYCHAIN_SERVICE = "Claude Code-credentials";
-/**
- * True when the machine has credentials the Claude Code binary can
- * authenticate with on its own: a stored `/login` session (keychain or
- * `$CLAUDE_CONFIG_DIR/.credentials.json`) or an explicit env credential.
- * Mirrors the SDK's own resolution; pome never reads the secret values.
- */
-export function detectClaudeLogin(env = process.env, home = homedir(), platform = process.platform) {
-    if (env.ANTHROPIC_API_KEY || env.CLAUDE_CODE_OAUTH_TOKEN || env.ANTHROPIC_AUTH_TOKEN) {
-        return true;
-    }
-    const configDir = env.CLAUDE_CONFIG_DIR || join(home, ".claude");
-    try {
-        if (existsSync(join(configDir, ".credentials.json")))
-            return true;
-    }
-    catch {
-        /* unreadable — treat as absent */
-    }
-    if (platform === "darwin") {
-        try {
-            const res = spawnSync("security", ["find-generic-password", "-s", CLAUDE_KEYCHAIN_SERVICE], { stdio: "ignore", timeout: 5000 });
-            if (res.status === 0)
-                return true;
-        }
-        catch {
-            /* lookup failed — treat as absent */
-        }
-    }
-    return false;
-}
-/** Directory the pinned SDK driver is provisioned into. */
-export function agentSdkDir(home = homedir()) {
-    return join(home, ".pome", "agent-sdk", AGENT_SDK_VERSION);
-}
-function sdkEntryPath(dir) {
-    return join(dir, "node_modules", "@anthropic-ai", "claude-agent-sdk", "sdk.mjs");
-}
-export function isAgentSdkProvisioned(dir = agentSdkDir()) {
-    return existsSync(sdkEntryPath(dir));
-}
-/**
- * Install the pinned driver into `dir` using whichever package manager is
- * on PATH. `--omit=optional` skips the ~244 MB platform runtime — the
- * session runs on the user's own `claude` binary instead.
- * Returns null (with a printed reason) when no package manager is found
- * or the install fails; callers fall back to the interactive session.
- */
-export async function provisionAgentSdk(dir = agentSdkDir()) {
-    await mkdir(dir, { recursive: true });
-    const manifest = join(dir, "package.json");
-    if (!existsSync(manifest)) {
-        await writeFile(manifest, JSON.stringify({ name: "pome-agent-sdk", private: true }, null, 2));
-    }
-    const spec = `@anthropic-ai/claude-agent-sdk@${AGENT_SDK_VERSION}`;
-    const attempts = [
-        ["npm", ["install", "--omit=optional", "--no-audit", "--no-fund", spec]],
-        ["bun", ["add", "--omit=optional", spec]],
-    ];
-    for (const [bin, args] of attempts) {
-        const probe = spawnSync(bin, ["--version"], { stdio: "ignore", timeout: 10_000 });
-        if (probe.error || probe.status !== 0)
-            continue;
-        console.error(`downloading the Claude Agent SDK driver (${spec}, a few MB, one-time) …`);
-        const res = spawnSync(bin, args, { cwd: dir, stdio: "ignore", timeout: 300_000 });
-        if (res.status === 0 && isAgentSdkProvisioned(dir))
-            return true;
-        console.error(`(${bin} install of ${spec} failed)`);
-    }
-    console.error("couldn't provision the Claude Agent SDK driver (is npm or bun on PATH?).");
-    return false;
-}
-/** Import the provisioned driver. Returns null when not provisioned. */
-export async function loadAgentSdk(dir = agentSdkDir()) {
-    const entry = sdkEntryPath(dir);
-    if (!existsSync(entry))
-        return null;
-    const mod = (await import(pathToFileURL(entry).href));
-    if (typeof mod.query !== "function")
-        return null;
-    return { query: mod.query };
-}

package/dist/src/cli/embedded-wiring.d.ts

@@ -1,47 +0,0 @@
-import type { AgentSdkQueryFn } from "./agent-sdk.js";
-/** Tools the staging session may use. Everything else — Bash above all —
- *  is refused: package installs and verification are pome's job, after
- *  the diff is approved. NOTE: never mirror these into `allowedTools`;
- *  bare allowedTools entries auto-approve before canUseTool is consulted. */
-export declare const STAGING_TOOLS: readonly ["Read", "Edit", "Write", "Glob", "Grep"];
-/** First message of the headless session. The pome-setup skill (injected
- *  into the shadow's .claude/skills) carries the wiring knowledge; this
- *  adapts its interactive contract to staging: edits land automatically,
- *  the human approves ONE combined diff in pome's terminal afterwards. */
-export declare const EMBEDDED_KICKOFF_PROMPT: string;
-export type EmbeddedWiringOutcome = {
-    kind: "applied";
-    files: number;
-    packageJsonChanged: boolean;
-} | {
-    kind: "declined";
-} | {
-    kind: "no-diff";
-    reason: string;
-} | {
-    kind: "session-error";
-    reason: string;
-};
-export interface EmbeddedWiringOptions {
-    /** The real repo root the approved diff is applied to. */
-    cwd: string;
-    /** The user's Claude Code binary — passed as pathToClaudeCodeExecutable. */
-    claudePath: string;
-    /** Packaged pome-setup skill directory (contains SKILL.md). */
-    skillSourceDir: string;
-    /** The provisioned SDK's query(). Injected — the test seam. */
-    query: AgentSdkQueryFn;
-    /** [y/N] prompt. */
-    confirm: (question: string) => Promise<boolean>;
-    /** Line sink, default console.error. */
-    log?: (line: string) => void;
-}
-export declare function runEmbeddedWiring(options: EmbeddedWiringOptions): Promise<EmbeddedWiringOutcome>;
-/** Path-confining permission gate. Exported for direct unit tests. */
-export declare function buildStagingCanUseTool(shadowRoot: string, log: (line: string) => void): (toolName: string, input: Record<string, unknown>) => Promise<{
-    behavior: "allow";
-    updatedInput: Record<string, unknown>;
-} | {
-    behavior: "deny";
-    message: string;
-}>;