snipara-companion 3.2.13 → 3.2.14

package/README.md

@@ -22,6 +22,27 @@ npx -y snipara-companion impact src/auth/session.ts --source local
 npx -y snipara-companion source init .
 ```
 
+## Companion Continuity Contract V1
+
+Editor integrations and post-activation workflows can ask Companion for one
+machine-readable "continue this workspace" payload:
+
+```bash
+npx -y snipara-companion@latest continue-workspace --include-session-context --json
+```
+
+The payload version is `snipara.companion.continuity.v1`. It is designed for
+native editor commands, status bars, panels, and agent handoffs that need to
+resume real work without rescanning or reimplementing Snipara semantics. It
+includes project binding, session bootstrap entries and quality warnings,
+workflow phase state, Team Sync handoff summary, passive source snapshot status,
+session snapshot summary, stable local artifact paths, and recommended next
+actions.
+
+Use this after `create-snipara` activation. `create-snipara` remains the
+canonical engine for first workspace setup; Companion owns the repeatable local
+continuity loop after that.
+
 Example output excerpt:
 
 ```text

package/dist/index.js

@@ -16928,6 +16928,7 @@ var MIN_WORKFLOW_SURFACE_TOKENS = 200;
 var STALE_BOOTSTRAP_MEMORY_DAYS = 90;
 var TASK_COMMIT_TIMEOUT_MS = 3e4;
 var FINAL_COMMIT_TIMEOUT_MS = 9e4;
+var COMPANION_CONTINUITY_CONTRACT_VERSION = "snipara.companion.continuity.v1";
 var FINAL_COMMIT_RETRY_TIMEOUT_MS = 45e3;
 var FINAL_COMMIT_SUMMARY_MAX_CHARS = 1200;
 var FINAL_COMMIT_RETRY_SUMMARY_MAX_CHARS = 600;
@@ -24482,6 +24483,191 @@ async function sessionBootstrapCommand(options) {
     printSessionBootstrapQuality(buildPrintedBootstrapQuality(printedBootstrap));
   }
 }
+function emptySessionMemoriesResult() {
+  return {
+    critical: { memories: [], count: 0, tokens: 0 },
+    daily: { memories: [], count: 0, tokens: 0 },
+    total_tokens: 0
+  };
+}
+function readLocalJsonFile(relativePath2) {
+  const absolutePath = path20.join(process.cwd(), relativePath2);
+  if (!fs21.existsSync(absolutePath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs21.readFileSync(absolutePath, "utf-8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function summarizeSourceSnapshot(snapshot) {
+  if (!snapshot) {
+    return {
+      status: "missing",
+      snapshotPath: path20.join(".snipara", "source", "latest.json"),
+      nextAction: "Run snipara-companion source sync --json after meaningful local code or docs movement."
+    };
+  }
+  const summary = snapshot.summary && typeof snapshot.summary === "object" && !Array.isArray(snapshot.summary) ? snapshot.summary : {};
+  return {
+    status: "present",
+    snapshotPath: path20.join(".snipara", "source", "latest.json"),
+    generatedAt: snapshot.generatedAt,
+    revision: snapshot.revision,
+    totalFiles: summary.totalFiles,
+    totalBytes: summary.totalBytes,
+    skipped: summary.skipped
+  };
+}
+function summarizeWorkflowStateForContinuity(workflow2) {
+  if (!workflow2) {
+    return {
+      status: "missing",
+      statePath: WORKFLOW_STATE_RELATIVE_PATH,
+      nextAction: "Run snipara-companion workflow start for multi-phase work."
+    };
+  }
+  return {
+    status: workflow2.status,
+    workflowId: workflow2.workflowId,
+    goal: workflow2.goal,
+    currentPhaseId: workflow2.currentPhaseId,
+    statePath: WORKFLOW_STATE_RELATIVE_PATH,
+    phases: workflow2.phases.map((phase) => ({
+      id: phase.id,
+      title: phase.title,
+      status: phase.status
+    }))
+  };
+}
+function summarizeTeamSyncForContinuity() {
+  const state = loadTeamSyncState();
+  const summary = buildTeamSyncSummary(state);
+  const latestHandoff = state.handoffs.at(-1);
+  return {
+    statePath: path20.relative(process.cwd(), getTeamSyncStatePath()),
+    activeWorkCount: summary.activeWorkCount,
+    staleWorkCount: summary.staleWorkCount,
+    completedWorkCount: summary.completedWorkCount,
+    archivedWorkCount: summary.archivedWorkCount,
+    handoffCount: summary.handoffCount,
+    latestHandoff: latestHandoff ? {
+      summary: latestHandoff.summary,
+      next: latestHandoff.next,
+      attention: latestHandoff.attention,
+      createdAt: latestHandoff.createdAt
+    } : null
+  };
+}
+function buildCompanionContinuityPayload(args) {
+  const config = args.configured ? loadConfig() : null;
+  const workflow2 = readWorkflowState2();
+  const sessionSnapshot = readSessionSnapshot();
+  const sourceSnapshot = readLocalJsonFile(path20.join(".snipara", "source", "latest.json"));
+  return {
+    version: COMPANION_CONTINUITY_CONTRACT_VERSION,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    configured: args.configured,
+    project: config ? {
+      projectId: config.projectId,
+      apiUrl: config.apiUrl,
+      sessionId: config.sessionId
+    } : null,
+    artifacts: {
+      workflowStatePath: WORKFLOW_STATE_RELATIVE_PATH,
+      teamSyncStatePath: path20.relative(process.cwd(), getTeamSyncStatePath()),
+      sessionSnapshotPath: path20.join(".snipara", "activity", "session.json"),
+      sourceSnapshotPath: path20.join(".snipara", "source", "latest.json")
+    },
+    bootstrap: args.bootstrap,
+    bootstrapQuality: args.bootstrapQuality,
+    localWarmSnapshot: {
+      storedEntries: args.warmSnapshotStoredEntries
+    },
+    sessionContext: {
+      included: args.includeSessionContext,
+      maxTokens: args.maxContextTokens
+    },
+    workflow: summarizeWorkflowStateForContinuity(workflow2),
+    teamSync: summarizeTeamSyncForContinuity(),
+    source: summarizeSourceSnapshot(sourceSnapshot),
+    sessionSnapshot: sessionSnapshot ? {
+      latestActivityAt: sessionSnapshot.summary.latestActivityAt,
+      latestTitle: sessionSnapshot.summary.latestActivityTitle,
+      latestKind: sessionSnapshot.summary.latestActivityKind,
+      risk: sessionSnapshot.summary.risk,
+      riskReasons: sessionSnapshot.summary.riskReasons,
+      touchedFiles: sessionSnapshot.summary.touchedFiles,
+      nextAction: sessionSnapshot.summary.recommendedNextAction
+    } : null,
+    nextActions: [
+      {
+        id: "open_bootstrap_brief",
+        label: "Open bootstrap brief",
+        command: "snipara-companion session-bootstrap --include-session-context --max-context-tokens 1000",
+        when: "bootstrap has entries or session context is included"
+      },
+      {
+        id: "refresh_source_snapshot",
+        label: "Refresh source snapshot",
+        command: "snipara-companion source sync --json",
+        when: "source.status is missing or local code/docs changed"
+      },
+      {
+        id: "run_impact_gate",
+        label: "Run code impact before risky edits",
+        command: 'snipara-companion code impact --changed-files <files> --diff-summary "next edit"',
+        when: "the next edit is multi-file, risky, or user-visible"
+      },
+      {
+        id: "commit_task_context",
+        label: "Commit durable task context",
+        command: 'snipara-companion task-commit --summary "<done>" --files <files>',
+        when: "a durable phase or task is complete"
+      }
+    ]
+  };
+}
+async function continueWorkspaceCommand(options) {
+  const configured = isConfigured();
+  const resolvedContextTokens = options.maxContextTokens !== void 0 ? options.maxContextTokens : options.includeSessionContext ? DEFAULT_SESSION_CONTEXT_TOKENS : 0;
+  let bootstrap = emptySessionMemoriesResult();
+  let warmSnapshotStoredEntries = 0;
+  if (configured) {
+    const client = createClient(15e3);
+    bootstrap = await client.getSessionMemories(options.maxCriticalTokens, resolvedContextTokens);
+    const config = loadConfig();
+    const warmSnapshot = createLocalQueryCache({
+      cwd: process.cwd(),
+      projectId: config.projectId,
+      sessionId: config.sessionId
+    }).storeWarmSnapshot(bootstrap);
+    warmSnapshotStoredEntries = warmSnapshot.storedEntries;
+  }
+  const bootstrapQuality = buildSessionBootstrapQuality(bootstrap, {
+    expectedMaxTokens: (options.maxCriticalTokens ?? DEFAULT_FULL_WORKFLOW_CRITICAL_TOKENS) + resolvedContextTokens
+  });
+  const payload = buildCompanionContinuityPayload({
+    configured,
+    bootstrap,
+    bootstrapQuality,
+    includeSessionContext: resolvedContextTokens > 0,
+    maxContextTokens: resolvedContextTokens,
+    warmSnapshotStoredEntries
+  });
+  if (options.json) {
+    printJson2(payload);
+    return;
+  }
+  console.log(import_chalk6.default.bold("Snipara Companion Continuity"));
+  console.log(`Version: ${COMPANION_CONTINUITY_CONTRACT_VERSION}`);
+  console.log(`Configured: ${configured ? "yes" : "no"}`);
+  console.log(`Workflow: ${payload.workflow.status ?? "unknown"}`);
+  console.log(`Source: ${payload.source.status ?? "unknown"}`);
+  console.log("Next: snipara-companion continue-workspace --json for editor integrations");
+}
 async function recallCommand(options) {
   ensureConfigured();
   const client = createClient(15e3);
@@ -34867,6 +35053,19 @@ program.command("session-bootstrap").description(
     json: options.json
   });
 });
+program.command("continue-workspace").description("Print the stable Companion Continuity Contract for editor integrations").option("--max-critical-tokens <number>", "Durable memory token budget").option(
+  "--include-session-context",
+  "Include short-lived session carryover in addition to durable memory"
+).option("--max-context-tokens <number>", "Short-lived session context token budget").option("--json", "Print raw JSON").action(async (options) => {
+  const maxCriticalTokens = options.maxCriticalTokens !== void 0 ? parseInt(options.maxCriticalTokens, 10) : void 0;
+  const maxContextTokens = options.maxContextTokens !== void 0 ? parseInt(options.maxContextTokens, 10) : void 0;
+  await continueWorkspaceCommand({
+    maxCriticalTokens,
+    maxContextTokens,
+    includeSessionContext: Boolean(options.includeSessionContext || options.maxContextTokens),
+    json: options.json
+  });
+});
 program.command("task-commit").description("Persist durable outcomes after meaningful task work, not every git commit").requiredOption("-s, --summary <summary>", "Task summary").option("-c, --category <category>", "Category").option("-o, --outcome <outcome>", "Outcome", "completed").option("-f, --files <files...>", "Files touched").option("--json", "Print raw JSON").action(async (options) => {
   await taskCommitCommand({
     summary: options.summary,

package/docs/FULL_REFERENCE.md

@@ -21,6 +21,35 @@ snipara-companion code impact --changed-files src/app.ts --diff-summary "next ed
 snipara-companion task-commit --summary "completed durable change" --files src/app.ts
 ```
 
+## Companion Continuity Contract V1
+
+For editor integrations and "continue this workspace" flows, use the stable JSON
+contract instead of rebuilding Companion internals:
+
+```bash
+snipara-companion continue-workspace --include-session-context --json
+```
+
+The response version is `snipara.companion.continuity.v1`. It includes:
+
+- `project`: configured project id, API URL, and session id when available.
+- `bootstrap` and `bootstrapQuality`: pushed session memories plus token,
+  freshness, and warning metadata.
+- `workflow`: active workflow id, goal, current phase, phase statuses, and local
+  state path.
+- `teamSync`: active/stale/completed counts and latest handoff summary.
+- `source`: passive `.snipara/source/latest.json` status; no source sync is
+  performed by this command.
+- `sessionSnapshot`: latest local activity summary, risks, touched files, and
+  recommended next action.
+- `artifacts` and `nextActions`: stable local paths and commands an editor can
+  surface to the user.
+
+This contract starts after `create-snipara` has activated the workspace. Editor
+extensions should orchestrate these commands and render the payload, not fork
+local source scanning, First Work Brief, memory candidate, or Hosted MCP config
+logic.
+
 In this repository, the source currently lives in `packages/cli`, and the installed executable is `snipara-companion`.
 
 This package complements `snipara-mcp`. It does not replace it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "3.2.13",
+  "version": "3.2.14",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {