@pome-sh/cli 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Pome CLI
 
-The `pome` command runs AI-agent scenarios against resettable digital twins of
+The `pome` command runs AI-agent tasks against resettable digital twins of
 real SaaS APIs (GitHub, Stripe, …), captures the trace, and gets a verdict from
 Pome cloud.
 
@@ -24,6 +24,18 @@ Or run it without installing: `npx @pome-sh/cli <command>` — e.g.
 `npx @pome-sh/cli twin start github` boots a local GitHub twin with nothing
 but Node ≥ 24.
 
+Gmail is first-party too:
+
+```bash
+npx @pome-sh/cli twin start gmail --port 3336
+# prints POME_GMAIL_REST_URL, POME_GMAIL_MCP_URL, and POME_GMAIL_TOKEN
+pome scenarios gmail --copy
+```
+
+`POME_GMAIL_TOKEN` is the same Pome session JWT as `POME_AUTH_TOKEN`; it is not
+a Google OAuth token. Hosted Gmail availability is gated separately from the
+local/OSS package release.
+
 ## Quickstart
 
 ```bash
@@ -41,7 +53,7 @@ pome run --local scenarios/01-bug-happy-path.md   # captures a raw trace only
 pome eval runs/01-bug-happy-path/<run-id>         # uploads it for a cloud verdict
 ```
 
-See [docs.pome.sh](https://docs.pome.sh) for the scenario library, exit-code
+See [docs.pome.sh](https://docs.pome.sh) for the task library, exit-code
 contract, authentication, the Stripe/Slack twins, and everything else.
 
 ## Development

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "package": "pome-sh",
-  "version": "0.3.0",
-  "git_sha": "a6d896782cc39f3d7c93a0f713d77594aef7441c",
-  "build_time": "2026-07-16T22:11:55.839Z"
+  "version": "0.4.0",
+  "git_sha": "724f504bafc5a7fa59b2b6a295f1529f03e3ece0",
+  "build_time": "2026-07-22T19:44:48.942Z"
 }

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

@@ -0,0 +1,20 @@
+export interface RunAgentIdentity {
+    /** The resolved agent id to send at session create; absent = unattributed. */
+    agentId?: string;
+    /** `--agent-version` override, else the manifest's `agent.version`. */
+    agentVersion?: string;
+    /** The manifest's `agent.framework` — the run's "SDK badge" on the dashboard. */
+    framework?: string;
+    /** The manifest's `agent.slug`, when a manifest is present. */
+    agentSlug?: string;
+}
+export interface ResolveRunAgentIdentityInput {
+    /** Directory to discover the manifest + link cache from (walks up). */
+    startDir: string;
+    apiBaseUrl: string;
+    /** `--agent-version` flag value; wins over the manifest's version. */
+    agentVersionOverride?: string;
+    /** Test seam — forwarded to resolveCredentials. */
+    credentialsPath?: string;
+}
+export declare function resolveRunAgentIdentity(input: ResolveRunAgentIdentityInput): Promise<RunAgentIdentity>;

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

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Run-path agent identity (F-819). Resolves the `agt_` id + version to stamp on
+// a hosted session from the committed manifest + gitignored `.pome/link.json`.
+//
+// The cached id is trusted only when its `team_id` matches the caller's team: a
+// re-clone under the same team short-circuits with no network (Champion TTHW);
+// a fork or team switch silently re-resolves the slug via `POST /v1/agents` so
+// a run never sends a foreign `agt_` id and self-onboards with zero extra
+// commands. A resolver hiccup degrades to "unattributed" rather than blocking a
+// local twin run.
+import { dirname } from "node:path";
+import { postAgentResolver, resolveSeams, } from "./agent-resolver.js";
+import { resolveCredentials } from "./credentials.js";
+import { ensurePomeGitignored, readLinkCache, resolveCachedAgentId, writeLinkCache, } from "./link-cache.js";
+import { readManifest } from "./project-config.js";
+export async function resolveRunAgentIdentity(input) {
+    const manifestRead = await readManifest(input.startDir);
+    if (!manifestRead) {
+        return input.agentVersionOverride
+            ? { agentVersion: input.agentVersionOverride }
+            : {};
+    }
+    const { agent } = manifestRead.manifest;
+    const agentVersion = input.agentVersionOverride ?? agent.version;
+    const base = {
+        agentVersion,
+        framework: agent.framework,
+        agentSlug: agent.slug,
+    };
+    const projectDir = dirname(manifestRead.path);
+    try {
+        const creds = await resolveCredentials({
+            apiBaseUrl: input.apiBaseUrl,
+            credentialsPath: input.credentialsPath,
+        });
+        const cachedId = resolveCachedAgentId(await readLinkCache(projectDir), creds.teamId);
+        if (cachedId) {
+            return { ...base, agentId: cachedId };
+        }
+        // Silent re-resolution — a run never prompts for a near-miss.
+        const resolved = await postAgentResolver(creds, {
+            name: agent.name ?? agent.slug,
+            slug: agent.slug,
+            description: agent.description,
+            version: agent.version,
+            framework: agent.framework,
+        }, resolveSeams({ stdinIsTTY: false }));
+        if (creds.teamId) {
+            await writeLinkCache(projectDir, { agent_id: resolved.id, team_id: creds.teamId });
+            await ensurePomeGitignored(projectDir);
+        }
+        return { ...base, agentId: resolved.id };
+    }
+    catch (err) {
+        console.error(`pome: could not resolve agent identity (${err instanceof Error ? err.message : String(err)}); running unattributed.`);
+        return base;
+    }
+}

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

@@ -0,0 +1,26 @@
+import { type AgentResponse } from "@pome-sh/shared-types";
+import type { ResolvedCredentials } from "./credentials.js";
+/** Test seams — default to a live TTY [y/N] prompt (mirrors install.ts). */
+export interface InteractiveSeams {
+    stdinIsTTY?: boolean;
+    confirm?: (question: string) => Promise<boolean>;
+}
+/** The manifest identity fields POSTed to the resolver. */
+export interface AgentPostBody {
+    name: string;
+    slug?: string;
+    description?: string;
+    version?: string;
+    framework?: string;
+    twins?: string[];
+    confirm?: boolean;
+}
+export declare function resolveSeams(opts: InteractiveSeams): Required<InteractiveSeams>;
+/** Extract the near-miss suggested slug from a 409 conflict envelope. F-820
+ *  returns it under `error.details.suggestion`; we also tolerate `suggestions[]`
+ *  and `slug` as forward-compatible fallbacks. */
+export declare function nearMissSuggestion(json: unknown): string | undefined;
+/** POST the manifest identity, resolving a 409 near-miss per the confirmation
+ *  UX: interactive → "did you mean X?" (yes re-resolves X, no force-creates the
+ *  typed slug); non-TTY/CI → warn + force-create (`confirm: true`). */
+export declare function postAgentResolver(creds: ResolvedCredentials, body: AgentPostBody, seams: Required<InteractiveSeams>): Promise<AgentResponse>;

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

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// The `POST /v1/agents` resolver round-trip (F-820), shared by `pome register`
+// (interactive near-miss) and the run paths (silent re-resolution of a
+// committed slug under the caller's team). Kept import-neutral — no register/
+// session dependency — so both sides can consume it without a cycle.
+import { createInterface } from "node:readline";
+import { agentResponseSchema } from "@pome-sh/shared-types";
+import { HostedAuthError, HostedOrchError } from "../hosted/errors.js";
+export function resolveSeams(opts) {
+    return {
+        stdinIsTTY: opts.stdinIsTTY ?? Boolean(process.stdin.isTTY),
+        confirm: opts.confirm ?? promptYesNo,
+    };
+}
+async function requestAgent(creds, body) {
+    const res = await fetch(`${creds.apiBaseUrl}/v1/agents`, {
+        method: "POST",
+        headers: { "x-api-key": creds.apiKey, "content-type": "application/json" },
+        body: JSON.stringify(prunePostBody(body)),
+    }).catch((err) => {
+        throw new HostedOrchError(err instanceof Error ? err.message : "network error");
+    });
+    const text = await res.text();
+    let json = {};
+    try {
+        json = text.length ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new HostedOrchError(`non-JSON response (status ${res.status})`);
+    }
+    return { ok: res.ok, status: res.status, json };
+}
+/** Drop undefined keys so the wire body stays byte-clean (older cloud, tests). */
+function prunePostBody(body) {
+    const out = { name: body.name };
+    if (body.slug !== undefined)
+        out.slug = body.slug;
+    if (body.description !== undefined)
+        out.description = body.description;
+    if (body.version !== undefined)
+        out.version = body.version;
+    if (body.framework !== undefined)
+        out.framework = body.framework;
+    if (body.twins && body.twins.length > 0)
+        out.twins = body.twins;
+    if (body.confirm !== undefined)
+        out.confirm = body.confirm;
+    return out;
+}
+function parseOkAgent(json) {
+    const parsed = agentResponseSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new HostedOrchError("POST /v1/agents returned an unexpected shape");
+    }
+    return parsed.data;
+}
+function mapHttpError(status, json) {
+    const err = json.error;
+    if (status === 401 || status === 403) {
+        return new HostedAuthError(err?.message ?? `HTTP ${status}`);
+    }
+    if (status === 404) {
+        return new HostedOrchError(err?.message ??
+            "POST /v1/agents is not available at this API URL. Upgrade pome-cloud or check that --api-url/POME_API_URL points at a version that supports agent registration.");
+    }
+    return new HostedOrchError(err?.message ?? `POST /v1/agents → HTTP ${status}`);
+}
+/** Extract the near-miss suggested slug from a 409 conflict envelope. F-820
+ *  returns it under `error.details.suggestion`; we also tolerate `suggestions[]`
+ *  and `slug` as forward-compatible fallbacks. */
+export function nearMissSuggestion(json) {
+    const error = json.error;
+    if (error?.type !== "conflict")
+        return undefined;
+    const details = error.details;
+    if (!details)
+        return undefined;
+    const candidate = details.suggestion ??
+        details.slug ??
+        (Array.isArray(details.suggestions) ? details.suggestions[0] : undefined);
+    return typeof candidate === "string" && candidate.length > 0 ? candidate : undefined;
+}
+/** POST the manifest identity, resolving a 409 near-miss per the confirmation
+ *  UX: interactive → "did you mean X?" (yes re-resolves X, no force-creates the
+ *  typed slug); non-TTY/CI → warn + force-create (`confirm: true`). */
+export async function postAgentResolver(creds, body, seams) {
+    const first = await requestAgent(creds, body);
+    if (first.ok)
+        return parseOkAgent(first.json);
+    if (first.status === 409) {
+        const suggestion = nearMissSuggestion(first.json);
+        if (suggestion) {
+            const interactive = seams.stdinIsTTY && !process.env.CI;
+            let retry;
+            if (interactive) {
+                const yes = await seams.confirm(`An agent named "${suggestion}" already exists on your team. Did you mean "${suggestion}"? [y/N] `);
+                retry = yes ? { ...body, slug: suggestion } : { ...body, confirm: true };
+            }
+            else {
+                console.error(`Near-miss: this slug is close to your team's existing "${suggestion}". Registering the new agent anyway (run interactively to link the existing one instead).`);
+                retry = { ...body, confirm: true };
+            }
+            const second = await requestAgent(creds, retry);
+            if (second.ok)
+                return parseOkAgent(second.json);
+            throw mapHttpError(second.status, second.json);
+        }
+    }
+    throw mapHttpError(first.status, first.json);
+}
+async function promptYesNo(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolve) => rl.question(question, resolve));
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/src/cli/compile-seeds.js

@@ -21,7 +21,7 @@ const SIDECAR_META_VERSION = 1;
 export async function runCompileSeeds(target, opts) {
     const files = await resolveScenarioFiles(target ?? "scenarios");
     if (files.length === 0) {
-        console.error(`No scenario .md files found at ${target ?? "scenarios"}.`);
+        console.error(`No task .md files found at ${target ?? "scenarios"}.`);
         return 2;
     }
     const results = [];

package/dist/src/cli/credentials.d.ts

@@ -9,6 +9,10 @@ export interface ResolveCredentialsInput {
 export interface ResolvedCredentials {
     apiKey: string;
     apiBaseUrl: string;
+    /** The team the api key belongs to, when known (stored at login). Powers the
+     *  `.pome/link.json` team gate (F-819). Undefined for a bare `POME_API_KEY`
+     *  env key, whose team is known only server-side. */
+    teamId?: string;
 }
 export interface CredentialsFile {
     api_key?: string;

package/dist/src/cli/credentials.js

@@ -50,6 +50,7 @@ export async function resolveCredentials(input) {
         return {
             apiKey: keychain.api_key.trim(),
             apiBaseUrl: resolveApiBaseUrl(input.apiBaseUrl, keychain.api_url),
+            teamId: normalizeTeamId(keychain.team_id),
         };
     }
     const path = input.credentialsPath ?? DEFAULT_PATH();
@@ -84,8 +85,15 @@ export async function resolveCredentials(input) {
     return {
         apiKey: parsed.api_key.trim(),
         apiBaseUrl: resolveApiBaseUrl(input.apiBaseUrl, parsed.api_url),
+        teamId: normalizeTeamId(parsed.team_id),
     };
 }
+function normalizeTeamId(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
 function resolveApiBaseUrl(callerInput, storedApiUrl) {
     const candidate = callerInput ?? storedApiUrl;
     if (typeof candidate !== "string" || candidate.trim().length === 0) {

package/dist/src/cli/docs-topics.js

@@ -59,6 +59,12 @@ export const DOCS_TOPICS = [
         path: "/docs/twins/slack",
         keywords: ["messaging", "channels", "workspace", "slack", "exfiltration"],
     },
+    {
+        id: "gmail",
+        title: "Gmail twin",
+        path: "/docs/twins/gmail",
+        keywords: ["email", "inbox", "drafts", "labels", "gmail", "mcp"],
+    },
     {
         id: "cli",
         title: "Command Line Interface",
@@ -81,7 +87,7 @@ export const DOCS_TOPICS = [
         id: "cli-scenarios",
         title: "pome scenarios",
         path: "/docs/cli/scenarios",
-        keywords: ["scenarios", "catalog", "copy", "library", "twin"],
+        keywords: ["tasks", "scenarios", "catalog", "copy", "library", "twin"],
     },
     {
         id: "cli-compile-seeds",
@@ -99,7 +105,7 @@ export const DOCS_TOPICS = [
         id: "cli-init",
         title: "pome init",
         path: "/docs/cli/init",
-        keywords: ["init", "scaffold", "pome.config.json", "project"],
+        keywords: ["init", "scaffold", "pome.json", "manifest", "project"],
     },
     {
         id: "troubleshooting",

package/dist/src/cli/eval.d.ts

@@ -1,7 +1,6 @@
 import { type HostedClient } from "../hosted/client.js";
 import { type UploadClient } from "../hosted/uploadAndFinalize.js";
 import { type Score } from "../hosted/evalResultView.js";
-import { type ProjectConfig } from "./project-config.js";
 /** The fields `writeRunArtifactsCore` persists to meta.json that `pome eval`
  *  relies on. Everything is optional-by-parse — validation happens in
  *  `deriveEvalIdentity` so the error can name the flag that fixes it. */
@@ -35,13 +34,18 @@ export interface EvalIdentity {
     agent: string;
     taskName: string;
 }
+/** The manifest fields `pome eval` reads: the agent slug (identity) and the
+ *  framework (the finalize "SDK badge"). */
+export interface EvalProjectIdentity {
+    agentSlug?: string;
+    framework?: string;
+}
 /** Precedence: explicit flags → meta.json (`scenario`, then `title`) for the
- *  task; explicit flag → pome.config.json (`agentSlug`, then `agentId`) for
- *  the agent. */
+ *  task; explicit flag → manifest `agent.slug` for the agent. */
 export declare function deriveEvalIdentity(meta: RunMeta, flags: {
     agent?: string;
     task?: string;
-}, config: ProjectConfig | null): EvalIdentity;
+}, identity: EvalProjectIdentity | null): EvalIdentity;
 /** The narrow client surface `runEval` needs; tests mock exactly this. */
 export type EvalClient = UploadClient & Pick<HostedClient, "createEvalSession" | "finalize">;
 export interface RunEvalOptions {
@@ -54,8 +58,8 @@ export interface RunEvalOptions {
     };
     /** For tests: inject a client. Otherwise constructed from `hosted`. */
     client?: EvalClient;
-    /** For tests: bypass pome.config.json discovery (pass null for "none"). */
-    projectConfig?: ProjectConfig | null;
+    /** For tests: bypass manifest discovery (pass null for "none"). */
+    projectConfig?: EvalProjectIdentity | null;
 }
 export interface RunEvalResult {
     taskName: string;

package/dist/src/cli/eval.js

@@ -28,7 +28,7 @@ import { readLatestRun, toTwinHttpEvent } from "../recorder/artifacts.js";
 import { redactEvent, redactSecrets } from "../recorder/redaction.js";
 import { criterionMarkerLabel, markerFor, outcomeOf, runScoreLine, scoreCountsSummary, scoreStatus, twinSkipSuffix, } from "../hosted/evalResultView.js";
 import { resolveCredentials } from "./credentials.js";
-import { normalizeConfigAgentSdk, readProjectConfig, } from "./project-config.js";
+import { readManifest } from "./project-config.js";
 import { isLegacyEventRow } from "../types/shared.js";
 const EVAL_SESSION_FILE = "eval-session.json";
 // The eval command has no scenario file (and therefore no per-scenario
@@ -68,7 +68,7 @@ async function readRequiredFile(runDir, name) {
     }
     catch (err) {
         if (err.code === "ENOENT") {
-            throw new HostedUsageError(`pome eval: ${name} not found in ${runDir} — expected a pome run directory (runs/<scenario>/<run-id>).`);
+            throw new HostedUsageError(`pome eval: ${name} not found in ${runDir} — expected a pome run directory (runs/<task>/<run-id>).`);
         }
         throw new HostedUsageError(`pome eval: ${name} could not be read: ${err instanceof Error ? err.message : String(err)}`);
     }
@@ -138,47 +138,39 @@ export async function readRunDirArtifacts(runDir) {
     };
 }
 /** Precedence: explicit flags → meta.json (`scenario`, then `title`) for the
- *  task; explicit flag → pome.config.json (`agentSlug`, then `agentId`) for
- *  the agent. */
-export function deriveEvalIdentity(meta, flags, config) {
+ *  task; explicit flag → manifest `agent.slug` for the agent. */
+export function deriveEvalIdentity(meta, flags, identity) {
     const taskName = flags.task?.trim() || meta.scenario || meta.title;
     if (!taskName) {
         throw new HostedUsageError("pome eval: could not derive a task name — meta.json has no `scenario` or `title` field. Pass --task <name>.");
     }
-    const agent = flags.agent?.trim() || configAgent(config);
+    const agent = flags.agent?.trim() || identity?.agentSlug?.trim() || "";
     if (!agent) {
-        throw new HostedUsageError("pome eval: no agent identity found. Pass --agent <slug>, or run `pome register agent <name>` so pome.config.json carries agentSlug.");
+        throw new HostedUsageError("pome eval: no agent identity found. Pass --agent <slug>, or run `pome register agent <name>` so pome.json carries agent.slug.");
     }
     return { agent, taskName };
 }
-function configAgent(config) {
-    if (!config)
-        return null;
-    const slug = typeof config.agentSlug === "string" ? config.agentSlug.trim() : "";
-    if (slug.length > 0)
-        return slug;
-    const id = typeof config.agentId === "string" ? config.agentId.trim() : "";
-    if (id.length > 0)
-        return id;
-    return null;
-}
 /** Walk up from the run dir first (in-project runs), then from the CWD
  *  (external run dirs like `pome eval /tmp/some-run` invoked from a
- *  configured project). Corrupt configs surface as named usage errors
- *  instead of raw JSON.parse throws (exit 2). */
+ *  configured project). Corrupt manifests surface as named usage errors
+ *  instead of raw parse throws (exit 2). */
 async function discoverProjectConfig(runDir) {
-    const fromRunDir = await readConfigNamed(runDir);
+    const fromRunDir = await readIdentityNamed(runDir);
     if (fromRunDir)
         return fromRunDir;
-    return readConfigNamed(process.cwd());
+    return readIdentityNamed(process.cwd());
 }
-async function readConfigNamed(startDir) {
+async function readIdentityNamed(startDir) {
+    let read;
     try {
-        return (await readProjectConfig(startDir))?.config ?? null;
+        read = await readManifest(startDir);
     }
     catch (err) {
-        throw new HostedUsageError(`pome eval: pome.config.json is corrupt — ${err instanceof Error ? err.message : String(err)}`);
+        throw new HostedUsageError(`pome eval: pome manifest is corrupt — ${err instanceof Error ? err.message : String(err)}`);
     }
+    if (!read)
+        return null;
+    return { agentSlug: read.manifest.agent.slug, framework: read.manifest.agent.framework };
 }
 // ---------------------------------------------------------------------------
 // eval-session persistence (idempotent re-runs)
@@ -237,10 +229,10 @@ function isSessionGoneError(err) {
 export async function runEval(options) {
     const runDir = options.runDir;
     const artifacts = await readRunDirArtifacts(runDir);
-    const config = options.projectConfig !== undefined
+    const projectIdentity = options.projectConfig !== undefined
         ? options.projectConfig
         : await discoverProjectConfig(runDir);
-    const identity = deriveEvalIdentity(artifacts.meta, { agent: options.agent, task: options.task }, config);
+    const identity = deriveEvalIdentity(artifacts.meta, { agent: options.agent, task: options.task }, projectIdentity);
     const { agent, taskName } = identity;
     const client = options.client ??
         createHostedClient({
@@ -310,7 +302,7 @@ export async function runEval(options) {
             exitCode: artifacts.meta.exitCode ?? -1,
             durationMs: durationMsFrom(artifacts.meta),
             agentModel: "unknown",
-            agentSdk: config ? normalizeConfigAgentSdk(config) : null,
+            agentSdk: projectIdentity?.framework ?? null,
             // Eval sessions carry no client-side criteria — the cloud eval judge
             // owns them (FDRS-655). Cloud's finalize schema defaults all scenario
             // fields, so empty strings are accepted.
@@ -391,7 +383,7 @@ export async function runEvalCommand(runDirArg, opts) {
                 throw new HostedUsageError(`pome eval: ${latestPath} is corrupt — not valid JSON (${err instanceof Error ? err.message : String(err)}).`);
             }
             if (!latest || typeof latest.run_dir !== "string" || latest.run_dir.length === 0) {
-                throw new HostedUsageError(`pome eval: no run directory given and ${latestPath} ${latest ? "has no run_dir field" : "not found"}. Pass a run directory (runs/<scenario>/<run-id>).`);
+                throw new HostedUsageError(`pome eval: no run directory given and ${latestPath} ${latest ? "has no run_dir field" : "not found"}. Pass a run directory (runs/<task>/<run-id>).`);
             }
             runDir = resolve(latest.run_dir);
         }

package/dist/src/cli/frameworks.d.ts

@@ -0,0 +1,12 @@
+/** Known agent frameworks. Open enum by design — this list drives the warning
+ *  suggestion only, never a hard rejection. */
+export declare const KNOWN_FRAMEWORKS: readonly ["langgraph", "claude-agent-sdk", "openai-agents", "crewai", "autogen", "llamaindex", "google-adk", "mastra", "pydantic-ai", "semantic-kernel"];
+export interface FrameworkSuggestion {
+    known: boolean;
+    /** Present only when unknown AND a known framework is within edit distance. */
+    suggestion?: string;
+}
+/** Classify a framework value. Known → `{ known: true }`. Unknown → `{ known:
+ *  false }`, with `suggestion` set to the nearest known value within edit
+ *  distance 2 (else omitted). Comparison is case-insensitive. */
+export declare function suggestFramework(input: string): FrameworkSuggestion;

package/dist/src/cli/frameworks.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Client-side did-you-mean for the manifest's open-enum `agent.framework`
+// (F-804 / F-819). An unknown framework is NEVER a validation error — the
+// manifest schema keeps it a free string. We only surface a friendly warning
+// with the nearest known value so a typo like "langraph" is caught locally
+// before it reaches the dashboard badge.
+/** Known agent frameworks. Open enum by design — this list drives the warning
+ *  suggestion only, never a hard rejection. */
+export const KNOWN_FRAMEWORKS = [
+    "langgraph",
+    "claude-agent-sdk",
+    "openai-agents",
+    "crewai",
+    "autogen",
+    "llamaindex",
+    "google-adk",
+    "mastra",
+    "pydantic-ai",
+    "semantic-kernel",
+];
+const MAX_SUGGEST_DISTANCE = 2;
+/** Classify a framework value. Known → `{ known: true }`. Unknown → `{ known:
+ *  false }`, with `suggestion` set to the nearest known value within edit
+ *  distance 2 (else omitted). Comparison is case-insensitive. */
+export function suggestFramework(input) {
+    const value = input.trim().toLowerCase();
+    if (KNOWN_FRAMEWORKS.includes(value)) {
+        return { known: true };
+    }
+    let best;
+    let bestDistance = MAX_SUGGEST_DISTANCE + 1;
+    for (const known of KNOWN_FRAMEWORKS) {
+        const distance = levenshtein(value, known);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = known;
+        }
+    }
+    if (best !== undefined && bestDistance <= MAX_SUGGEST_DISTANCE) {
+        return { known: false, suggestion: best };
+    }
+    return { known: false };
+}
+function levenshtein(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    const prev = new Array(cols);
+    const curr = new Array(cols);
+    for (let j = 0; j < cols; j += 1)
+        prev[j] = j;
+    for (let i = 1; i < rows; i += 1) {
+        curr[0] = i;
+        for (let j = 1; j < cols; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        for (let j = 0; j < cols; j += 1)
+            prev[j] = curr[j];
+    }
+    return prev[cols - 1];
+}

package/dist/src/cli/install.js

@@ -48,7 +48,7 @@ export const KICKOFF_PROMPT = "Use the pome-setup skill to wire this repository
  *  (their agent won't have the pome-setup skill installed). */
 export const PASTE_PROMPT = [
     "Wire this repository to pome (https://pome.sh) so its agent runs against a twin in test:",
-    "1. If pome.config.json is missing, run `pome init`; set agent.command to how this agent starts.",
+    "1. If pome.json is missing, run `pome init`; set the top-level command to how this agent starts.",
     "2. Claude Agent SDK repos: add @pome-sh/adapter-claude-sdk, import query/tool from it (drop-in replacements), and call withPome() once at startup.",
     "3. Replace every hardcoded production API host (e.g. https://api.github.com) with the env the pome runner injects: read POME_GITHUB_REST_URL / POME_GITHUB_MCP_URL and POME_AUTH_TOKEN from process.env. Never write secrets or URLs into source.",
     "4. Make minimal, targeted edits and show each diff for approval before applying.",
@@ -215,7 +215,7 @@ export async function runInstall(options) {
         }
     }
     // 6. FDRS-669 — register the agent (idempotent) now that the session has
-    // had its chance to create pome.config.json. Runs before the doctor verify
+    // had its chance to create pome.json. Runs before the doctor verify
     // so even a red-doctor install leaves the repo registered: the first bare
     // `pome run` submits under this agent, and "Default agent" stays a
     // migration-era state only (Reliability IA v1, decision 2).
@@ -239,7 +239,7 @@ export async function runInstall(options) {
     if (report.ok) {
         console.error("wiring verified — your agent is ready.");
         console.error("");
-        console.error("next: pome scenarios github --copy      # pull runnable scenarios into ./scenarios/");
+        console.error("next: pome scenarios github --copy      # pull runnable tasks into ./scenarios/");
         console.error("      pome run scenarios/01-bug-happy-path.md");
         return;
     }
@@ -402,8 +402,8 @@ function printManualFallback() {
     console.error(`no coding agent found on PATH (looked for: ${KNOWN_AGENTS.map((a) => a.bin).join(", ")}).`);
     console.error("");
     console.error("wire it manually:");
-    console.error("  1. config       pome init                  # if pome.config.json is missing;");
-    console.error("                                              # then set agent.command to your agent's start command");
+    console.error("  1. config       pome init                  # if pome.json is missing;");
+    console.error("                                              # then set the top-level command to your agent's start command");
     console.error("  2. adapter      npm install @pome-sh/adapter-claude-sdk");
     console.error('  3. hook + env   import { withPome } from "@pome-sh/adapter-claude-sdk"; withPome();');
     console.error("                  read the twin URL from env, never hardcode:");

package/dist/src/cli/link-cache.d.ts

@@ -0,0 +1,23 @@
+export declare const POME_DIR = ".pome";
+export declare const LINK_FILE = "link.json";
+export interface LinkCache {
+    agent_id: string;
+    team_id: string;
+    resolved_at: string;
+}
+/** Read the link cache next to a manifest. Missing or malformed → null: this
+ *  is a cache, never a hard failure (a bad file just forces re-resolution). */
+export declare function readLinkCache(projectDir: string): Promise<LinkCache | null>;
+/** Persist `.pome/link.json`, stamping `resolved_at` now. Creates `.pome/`. */
+export declare function writeLinkCache(projectDir: string, entry: {
+    agent_id: string;
+    team_id: string;
+}): Promise<void>;
+/** The team gate: the cached id is usable only when it was resolved under the
+ *  caller's own team. Any mismatch (or unknown caller team) → undefined, so the
+ *  caller re-resolves by slug instead of sending a foreign `agt_` id. */
+export declare function resolveCachedAgentId(cache: LinkCache | null, callerTeamId: string | undefined): string | undefined;
+/** Ensure the project's `.gitignore` ignores `.pome/`. Creates the file when
+ *  absent; appends the entry when missing. Idempotent, and a bare `.pome`
+ *  (no trailing slash) already counts as ignored. */
+export declare function ensurePomeGitignored(projectDir: string): Promise<void>;