@pome-sh/cli 0.1.0 → 0.2.0

package/dist/src/cli/session.js

@@ -2,7 +2,8 @@
 import { randomUUID } from "node:crypto";
 import { chmod, mkdir, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { createHostedClient } from "../hosted/client.js";
+import { MOUNTED_TWINS } from "@pome-sh/shared-types";
+import { createHostedClient, perTwinReturnedByCloud } from "../hosted/client.js";
 import { HostedAuthError, HostedOrchError, HostedQuotaError, } from "../hosted/errors.js";
 import { resolveCredentials } from "./credentials.js";
 import { DEFAULT_DASHBOARD_URL } from "./defaults.js";
@@ -12,10 +13,13 @@ import { normalizeConfigAgentId, readProjectConfig } from "./project-config.js";
 // standalone `pome twin start` path already appends `/mcp` in `cli/main.ts`;
 // mirror that here so agents reading the printed value get a working MCP URL
 // regardless of which side ships the fix first.
-function ensureMcpSuffix(url) {
+export function ensureMcpSuffix(url) {
     return /\/mcp\/?$/.test(url) ? url : `${url.replace(/\/$/, "")}/mcp`;
 }
-const ALLOWED_TWINS = new Set(["github", "stripe"]);
+// Multi-twin (M3): the CLI's ad-hoc session allowlist is the shared mounted-twin
+// set (github, stripe, slack). Slack is now reachable; repeated `--twin` flags
+// stand up a multi-twin session in one call.
+const ALLOWED_TWINS = new Set(MOUNTED_TWINS);
 function redactSession(res) {
     const pcIn = res.provider_credentials;
     const pcOut = {};
@@ -25,6 +29,9 @@ function redactSession(res) {
     if (pcIn.stripe) {
         pcOut.stripe = { ...pcIn.stripe, api_key: "***redacted***" };
     }
+    if (pcIn.slack) {
+        pcOut.slack = { ...pcIn.slack, token: "***redacted***" };
+    }
     return {
         session_id: res.session_id,
         session_token: res.session_token ? "***redacted***" : res.session_id,
@@ -36,34 +43,74 @@ function redactSession(res) {
         agent_token: "***redacted***",
     };
 }
-function formatEnvExport(res, twin) {
+function formatEnvExport(res, twins) {
     const lines = [
-        `# Pome hosted session — treat as secret. Twin: ${twin}`,
+        `# Pome hosted session — treat as secret. Twins: ${twins.join(", ")}`,
         `export POME_AUTH_TOKEN=${JSON.stringify(res.agent_token)}`,
         `export POME_SESSION_ID=${JSON.stringify(res.session_id)}`,
+        // Legacy single-endpoint URL (= the primary twin's api_url). Kept for
+        // agents written against the pre-multi-twin contract.
         `export POME_TWIN_URL=${JSON.stringify(res.twin_url)}`,
+        `export POME_TWIN_NAMES=${JSON.stringify(twins.join(","))}`,
     ];
-    if (res.per_twin?.[twin]?.api_url) {
-        lines.push(`export POME_${twin.toUpperCase()}_API_URL=${JSON.stringify(res.per_twin[twin].api_url)}`);
-    }
-    const gh = res.provider_credentials.github;
-    if (gh) {
-        lines.push(`export POME_GITHUB_TOKEN=${JSON.stringify(gh.token)}`);
-    }
-    const st = res.provider_credentials.stripe;
-    if (st) {
-        lines.push(`export POME_STRIPE_API_KEY=${JSON.stringify(st.api_key)}`);
-        if (res.per_twin?.[twin]?.api_url) {
-            lines.push(`export POME_STRIPE_API_BASE=${JSON.stringify(res.per_twin[twin].api_url)}`);
+    // Only trust per_twin.mcp_url when the cloud actually returned per_twin —
+    // the schema synthesizes mcp.pome.sh entries for old-cloud bodies, and those
+    // hosts don't serve MCP. Otherwise derive <api_url>/mcp (the legacy shape).
+    const fromCloud = perTwinReturnedByCloud(res);
+    // Multi-twin (M3): one POME_<TWIN>_{REST,MCP}_URL pair per twin, plus the
+    // provider-specific credential line. Loops per_twin so a github+slack session
+    // emits distinct endpoints for each.
+    for (const twin of twins) {
+        const upper = twin.toUpperCase();
+        const pt = res.per_twin?.[twin];
+        if (pt?.api_url) {
+            const mcpUrl = fromCloud ? ensureMcpSuffix(pt.mcp_url) : ensureMcpSuffix(pt.api_url);
+            lines.push(`export POME_${upper}_REST_URL=${JSON.stringify(pt.api_url)}`);
+            lines.push(`export POME_${upper}_MCP_URL=${JSON.stringify(mcpUrl)}`);
+        }
+        if (twin === "github") {
+            const gh = res.provider_credentials.github;
+            if (gh) {
+                lines.push(`export POME_GITHUB_TOKEN=${JSON.stringify(gh.token)}`);
+            }
+        }
+        else if (twin === "stripe") {
+            const st = res.provider_credentials.stripe;
+            if (st) {
+                lines.push(`export POME_STRIPE_API_KEY=${JSON.stringify(st.api_key)}`);
+            }
+            if (pt?.api_url) {
+                lines.push(`export POME_STRIPE_API_BASE=${JSON.stringify(pt.api_url)}`);
+            }
+        }
+        else if (twin === "slack") {
+            // The twin proxy verifies only the session JWT (agent_token) as bearer —
+            // the provider-specific Slack credential is NOT accepted at the proxy
+            // (same rationale as the Stripe api-key line in the hosted runner). So
+            // the agent's Slack bearer is the JWT, not provider_credentials.slack.token.
+            lines.push(`export POME_SLACK_TOKEN=${JSON.stringify(res.agent_token)}`);
         }
     }
     return `${lines.join("\n")}\n`;
 }
-export async function runSessionCreate(opts) {
-    const twin = opts.twin.trim().toLowerCase();
-    if (!ALLOWED_TWINS.has(twin)) {
-        throw new Error(`Unknown twin "${opts.twin}". V1 supports: ${[...ALLOWED_TWINS].join(", ")}.`);
+/** Normalize one-or-more `--twin` flags into a validated, de-duped twin list.
+ *  Repeated flags stand up an ad-hoc multi-twin session; each is validated
+ *  against MOUNTED_TWINS for a friendly error before the round-trip. */
+export function normalizeSessionTwins(raw) {
+    const twins = raw.map((t) => t.trim().toLowerCase()).filter((t) => t.length > 0);
+    for (const twin of twins) {
+        if (!ALLOWED_TWINS.has(twin)) {
+            throw new Error(`Unknown twin "${twin}". Supported: ${[...ALLOWED_TWINS].join(", ")}.`);
+        }
+    }
+    const deduped = [...new Set(twins)];
+    if (deduped.length === 0) {
+        throw new Error(`No twin specified. Pass --twin <name> (repeat for multi-twin). Supported: ${[...ALLOWED_TWINS].join(", ")}.`);
     }
+    return deduped;
+}
+export async function runSessionCreate(opts) {
+    const twins = normalizeSessionTwins(opts.twins);
     const creds = await resolveCredentials({ apiBaseUrl: opts.apiBaseUrl });
     const client = createHostedClient({
         baseUrl: creds.apiBaseUrl,
@@ -74,13 +121,13 @@ export async function runSessionCreate(opts) {
         ? normalizeConfigAgentId(configRead.config)
         : undefined;
     const session = await client.createSession({
-        twins: [twin],
+        twins,
         scenarioSource: "# ..\n",
         idempotencyKey: randomUUID(),
         agentId,
     });
     if (opts.secretsFile) {
-        await writeSecretsFile(opts.secretsFile, formatEnvExport(session, twin));
+        await writeSecretsFile(opts.secretsFile, formatEnvExport(session, twins));
         console.error(`Wrote session secrets to ${opts.secretsFile} (mode 0600).`);
     }
     if (opts.format === "json") {
@@ -98,11 +145,24 @@ export async function runSessionCreate(opts) {
     }
     console.error(`Session: ${session.session_id}`);
     console.error(`Expires: ${session.expires_at}`);
-    if (session.per_twin?.[twin]) {
-        console.error(`API: ${session.per_twin[twin].api_url}`);
-        console.error(`MCP: ${ensureMcpSuffix(session.per_twin[twin].mcp_url)}`);
+    // Multi-twin (M3): print one API/MCP line per twin so a github+slack session
+    // shows both endpoints. Falls back to the legacy bare twin_url on an older
+    // cloud that only ships it.
+    let printedAny = false;
+    const mcpFromCloud = perTwinReturnedByCloud(session);
+    for (const twin of twins) {
+        const pt = session.per_twin?.[twin];
+        if (pt) {
+            const label = twins.length > 1 ? `${twin} ` : "";
+            // Synthesized per_twin entries carry an mcp.pome.sh host that doesn't
+            // serve MCP — derive <api_url>/mcp unless the cloud returned per_twin.
+            const mcpUrl = mcpFromCloud ? ensureMcpSuffix(pt.mcp_url) : ensureMcpSuffix(pt.api_url);
+            console.error(`${label}API: ${pt.api_url}`);
+            console.error(`${label}MCP: ${mcpUrl}`);
+            printedAny = true;
+        }
     }
-    else {
+    if (!printedAny) {
         // Fallback for older cloud responses that only ship twin_url. Drop the
         // "(legacy)" label that confused users into thinking the URL was
         // deprecated (F21) — it's just the un-disambiguated single endpoint.

package/dist/src/demo/runDemo.js

@@ -35,8 +35,8 @@ import { newGroupId } from "./ids.js";
 import { mintDemoSessions } from "./mint.js";
 import { criterionPhrase, evaluatingLine, reassuranceBox, summaryLines, trialLine, trialsHeaderLine, twinReadyLine, } from "./render.js";
 import { DEMO_REPO, DEMO_TASK_NAME, demoTaskPath } from "./task.js";
-/** Explicit finalize timeout — the hosted client defaults to 30s; the demo
- *  judge measured 5-8s, 60s is belt-and-braces ([DECISION]). */
+/** Explicit overall finalize timeout — the demo judge measured 5-8s, 60s is
+ *  belt-and-braces ([DECISION]). */
 const DEMO_FINALIZE_TIMEOUT_MS = 60_000;
 export async function runDemo(options) {
     const out = options.out ?? ((line) => console.error(line));
@@ -50,6 +50,7 @@ export async function runDemo(options) {
             apiKey: session.demo_token,
             authScheme: "bearer",
             timeoutMs: DEMO_FINALIZE_TIMEOUT_MS,
+            finalizeTimeoutMs: DEMO_FINALIZE_TIMEOUT_MS,
         }));
     const groupId = newGroupId();
     const scenarioPath = demoTaskPath();

package/dist/src/doctor/checks.js

@@ -97,8 +97,8 @@ async function checkTwinReachable(_configDir) {
     });
     let harness;
     try {
-        // Dynamic import: the twin harness pulls in better-sqlite3, which the
-        // hosted-mode gate must never load better-sqlite3 unnecessarily.
+        // Dynamic import: the twin harness pulls in the twin packages and their
+        // node:sqlite-backed state, which the hosted-mode gate must never load.
         const { bootTwin } = await import("../twin/twinHarness.js");
         harness = await bootTwin({
             twin: "github",

package/dist/src/hosted/client.d.ts

@@ -1,4 +1,15 @@
-import { type CreateEvalSessionResponse, type CreateSessionResponse, type CriterionDef, type FinalizeResponse, type SessionPublic, type SubmitResultResponse, type CriterionResult, type Lane, type Step } from "../types/shared.js";
+import { type CreateEvalSessionResponse, type CreateSessionResponse, type CriterionDef, type FinalizeResponse, type SessionPublic, type SubmitResultResponse, type CriterionResult, type Lane, type PerTwinStateKeys, type Step } from "../types/shared.js";
+/** True when the cloud's create-session body actually returned a `per_twin`
+ *  key (empty `{}` counts) — i.e. `per_twin` was NOT synthesized by the schema
+ *  from a legacy `twin_url`-only response. Consumers use this to decide whether
+ *  `per_twin[twin].mcp_url` is trustworthy. */
+export declare function perTwinReturnedByCloud(session: CreateSessionResponse): boolean;
+/** Whether a raw create-session wire body carried a usable `per_twin` map
+ *  (before schema synthesis). A `per_twin: null` counts as absent — the schema
+ *  would synthesize entries for it, and synthesized URLs must not be trusted.
+ *  Exported so the runner's env unit test can model the exact provenance the
+ *  client stamps. */
+export declare function rawBodyHadPerTwin(raw: unknown): boolean;
 export interface HostedClientConfig {
     baseUrl: string;
     /** Team API key (`pme_…`) — or, with `authScheme: "bearer"`, a
@@ -7,6 +18,13 @@ export interface HostedClientConfig {
     /** Per-request timeout. Defaults to 30s; the cloud's own twin spawn is
      *  ~2s cold but we leave headroom for GHCR pulls.  */
     timeoutMs?: number;
+    /** Overall time allowed for finalize request + asynchronous polling to
+     * reach a terminal state. Defaults to five minutes. */
+    finalizeTimeoutMs?: number;
+    /** Initial async-finalize polling delay. Defaults to 500ms. */
+    finalizePollInitialDelayMs?: number;
+    /** Maximum async-finalize polling delay. Defaults to 5s. */
+    finalizePollMaxDelayMs?: number;
     /** FDRS-643 — how the credential travels. "x-api-key" (default) is the
      *  team-key contract. "bearer" sends `Authorization: Bearer <apiKey>` for
      *  the session-token surface (upload-url/finalize accept a sid-scoped JWT
@@ -86,9 +104,17 @@ export interface StateUploadUrlEntry {
     url: string;
     key: string;
 }
+export interface StateUploadUrlPair {
+    state_initial: StateUploadUrlEntry;
+    state_final: StateUploadUrlEntry;
+}
 export interface StateUploadUrlResponse {
     state_initial: StateUploadUrlEntry;
     state_final: StateUploadUrlEntry;
+    /** Multi-twin (M3): one initial/final URL+key pair per twin, keyed by twin
+     *  id. Absent on single-twin sessions and on an older cloud, where the
+     *  top-level pair (= primary twin) is authoritative. */
+    per_twin?: Record<string, StateUploadUrlPair>;
 }
 export interface SignalsUploadUrlResponse {
     url: string;
@@ -114,6 +140,11 @@ export interface FinalizeInput {
     stateInitialStorageKey?: string;
     stateFinalStorageKey?: string;
     signalsStorageKey?: string;
+    perTwinStateKeys?: PerTwinStateKeys;
+}
+export interface FinalizeOptions {
+    /** Cancels the finalize POST, any status request, or a pending poll delay. */
+    signal?: AbortSignal;
 }
 export interface HostedClient {
     createSession(input: CreateSessionInput): Promise<CreateSessionResponse>;
@@ -128,7 +159,7 @@ export interface HostedClient {
     fetchState(input: FetchOnTwinInput): Promise<unknown>;
     fetchEvents(input: FetchOnTwinInput): Promise<unknown[]>;
     /** ADR-013 — authoritative run finalize. Cloud judges and returns the score. */
-    finalize(sessionId: string, input: FinalizeInput): Promise<FinalizeResponse>;
+    finalize(sessionId: string, input: FinalizeInput, options?: FinalizeOptions): Promise<FinalizeResponse>;
     /**
      * @deprecated Use `finalize` instead. `/v1/sessions/:id/result` is a shim
      * kept for ≥1 OSS CLI release per ADR-013; cloud ignores the CLI-supplied
@@ -145,10 +176,15 @@ export interface HostedClient {
         errorCode?: string;
     }): Promise<AbandonSessionResponse>;
     requestEventsUploadUrl(sessionId: string): Promise<EventsUploadUrlResponse>;
-    requestStateUploadUrl(sessionId: string): Promise<StateUploadUrlResponse>;
+    /** Multi-twin (M3): pass `twins` (>1) to receive a per-twin URL+key pair
+     *  under `per_twin` in addition to the top-level primary-twin pair. Omit for
+     *  single-twin sessions. An older cloud ignores the body and returns only
+     *  the top-level pair. */
+    requestStateUploadUrl(sessionId: string, twins?: string[]): Promise<StateUploadUrlResponse>;
     /** F0-4 / L7 — mint a signed PUT for `signals.jsonl` (adapter-emitted
-     *  HookEvent / ToolUseEvent / SubagentSpawnEvent rows). The returned
-     *  `key` flows into `FinalizeInput.signalsStorageKey`. */
+     *  HookEvent / ToolUseEvent / ToolResultEvent / SubagentSpawnEvent /
+     *  LlmTurnEvent rows). The returned `key` flows into
+     *  `FinalizeInput.signalsStorageKey`. */
     requestSignalsUploadUrl(sessionId: string): Promise<SignalsUploadUrlResponse>;
     /** D18.1 — mint a signed PUT for meta.json. See `MetaUploadUrlResponse`
      *  for the feature-detection contract (a 404 here means an older control