sentinelayer-cli 0.30.14 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.30.14",
+  "version": "0.31.1",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/mcp.js

@@ -8,6 +8,7 @@ import fs from "node:fs/promises";
 
 import {
   buildAidenIdProvisioningAdapterTemplate,
+  buildHostedSentiSessionConnectorContract,
   buildAidenIdRegistryTemplate,
   buildMcpToolRegistrySchema,
   buildMcpServerConfigTemplate,
@@ -15,10 +16,12 @@ import {
   buildVsCodeMcpBridgeTemplate,
   readJsonFile,
   resolveDefaultAidenIdAdapterContractPath,
+  resolveDefaultHostedSentiSessionConnectorContractPath,
   resolveDefaultMcpOutputPath,
   resolveDefaultMcpServerConfigPath,
   resolveDefaultVsCodeBridgePath,
   validateAidenIdAdapterContract,
+  validateHostedSentiSessionConnectorContract,
   stringifyJson,
   validateMcpServerConfig,
   validateMcpToolRegistry,
@@ -255,6 +258,46 @@ export function registerMcpCommand(program) {
       console.log(pc.gray("Next: run 'sl mcp server init --id sentinelayer-session --registry-file <path>'."));
     });
 
+  registry
+    .command("init-hosted-session-connector")
+    .description("Write the hosted Senti session MCP connector contract")
+    .option(
+      "--registry-file <path>",
+      "Local session registry file referenced by hosted connector contract",
+      ".sentinelayer/mcp/tool-registry.session-tools.json"
+    )
+    .option("--path <path>", "Destination file path override")
+    .option("--output-dir <path>", "Optional artifact output root override")
+    .option("--force", "Overwrite destination file if it already exists")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const defaultPath = await resolveDefaultHostedSentiSessionConnectorContractPath({
+        cwd: process.cwd(),
+        outputDir: options.outputDir,
+        env: process.env,
+      });
+      const outputPath = normalizeOutputPath(options.path, defaultPath);
+      const template = buildHostedSentiSessionConnectorContract({
+        localRegistryFile: options.registryFile,
+      });
+      validateHostedSentiSessionConnectorContract(template);
+      const writtenPath = await writeJsonFile(outputPath, template, { force: Boolean(options.force) });
+      const payload = {
+        command: "mcp registry init-hosted-session-connector",
+        outputPath: writtenPath,
+        localRegistryFile: template.local_registry_file,
+        toolCount: template.tools.length,
+        tools: template.tools.map((tool) => tool.tool_name),
+      };
+
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(pc.green(`Wrote hosted Senti session connector contract: ${writtenPath}`));
+      console.log(pc.gray("This is a hosted connector contract, not a local stdio runtime claim."));
+    });
+
   registry
     .command("init-cli")
     .description("Write a generated MCP registry for every SentinelLayer CLI leaf command")
@@ -335,6 +378,66 @@ export function registerMcpCommand(program) {
       }
     });
 
+  registry
+    .command("validate-hosted-session-connector")
+    .description("Validate a hosted Senti session MCP connector contract")
+    .requiredOption("--file <path>", "Hosted connector contract JSON file to validate")
+    .option("--registry-file <path>", "Optional local session registry JSON file for cross-check")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const inputPath = path.resolve(process.cwd(), String(options.file || "").trim());
+      const loaded = await readJsonFile(inputPath);
+      const registryFile = String(options.registryFile || "").trim();
+      const loadedRegistry = registryFile
+        ? await readJsonFile(path.resolve(process.cwd(), registryFile))
+        : null;
+
+      let parsed;
+      try {
+        parsed = validateHostedSentiSessionConnectorContract(loaded.data, {
+          registryPayload: loadedRegistry ? loadedRegistry.data : undefined,
+        });
+      } catch (error) {
+        const payload = {
+          command: "mcp registry validate-hosted-session-connector",
+          valid: false,
+          filePath: loaded.path,
+          registryFilePath: loadedRegistry ? loadedRegistry.path : null,
+          error: zodIssueSummary(error),
+        };
+        if (shouldEmitJson(options, command)) {
+          console.log(JSON.stringify(payload, null, 2));
+        } else {
+          console.log(pc.red(`Hosted Senti session connector contract invalid: ${payload.error}`));
+          console.log(pc.gray(`File: ${loaded.path}`));
+          if (payload.registryFilePath) {
+            console.log(pc.gray(`Registry: ${payload.registryFilePath}`));
+          }
+        }
+        process.exitCode = 2;
+        return;
+      }
+
+      const payload = {
+        command: "mcp registry validate-hosted-session-connector",
+        valid: true,
+        filePath: loaded.path,
+        registryFilePath: loadedRegistry ? loadedRegistry.path : null,
+        connector: parsed.connector,
+        toolCount: parsed.tools.length,
+        releaseGateCount: parsed.release_gates.length,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(pc.green(`Hosted Senti session connector contract valid (${parsed.tools.length} tools)`));
+      console.log(pc.gray(`File: ${loaded.path}`));
+      if (payload.registryFilePath) {
+        console.log(pc.gray(`Registry: ${payload.registryFilePath}`));
+      }
+    });
+
   registry
     .command("validate-aidenid-adapter")
     .description(

package/src/mcp/registry.js

@@ -12,6 +12,8 @@ export const MCP_TOOL_REGISTRY_SCHEMA_VERSION = "1.0.0";
 export const MCP_SERVER_CONFIG_SCHEMA_VERSION = "1.0.0";
 /** AIdenID adapter-contract schema version used by Sentinelayer CLI generated artifacts. */
 export const AIDENID_ADAPTER_CONTRACT_SCHEMA_VERSION = "1.0.0";
+/** Hosted Senti session connector-contract schema version. */
+export const HOSTED_SENTI_SESSION_CONNECTOR_CONTRACT_SCHEMA_VERSION = "1.0.0";
 
 const serverIdRegex = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
 const inputPlaceholderRegex = /^\{\{input\.[a-zA-Z0-9_.-]+\}\}$/;
@@ -142,6 +144,113 @@ const aidenIdAdapterContractSchema = z
   })
   .strict();
 
+const hostedSessionConnectorToolSchema = z
+  .object({
+    tool_name: z
+      .string()
+      .min(1)
+      .regex(/^[a-zA-Z0-9_.:-]+$/, "tool_name must contain only [a-zA-Z0-9_.:-]"),
+    local_tool_name: z
+      .string()
+      .min(1)
+      .regex(/^[a-zA-Z0-9_.:-]+$/, "local_tool_name must contain only [a-zA-Z0-9_.:-]"),
+    operation: z.enum([
+      "join_and_hydrate",
+      "read_history",
+      "send_message",
+      "session_action",
+      "session_lock",
+      "session_unlock",
+      "list_locks",
+      "attention_request",
+      "subscribe_wake",
+      "presence_renew",
+      "runner_teardown",
+    ]),
+    input_policy: z
+      .object({
+        identity_source: z.literal("server_session_seat"),
+        rejects_identity_from_tool_args: z.literal(true),
+        allowed_user_args: z.array(z.string().min(1)).default([]),
+        forbidden_capability_args: z
+          .array(z.enum(["sessionId", "session_id", "agentId", "agent_id", "userId", "user_id", "orgId", "org_id"]))
+          .default(["sessionId", "session_id", "agentId", "agent_id", "userId", "user_id", "orgId", "org_id"]),
+      })
+      .strict(),
+    authorization: z
+      .object({
+        requires_validated_claims: z.literal(true),
+        requires_session_seat: z.literal(true),
+        required_scopes: z.array(z.string().min(1)).min(1),
+      })
+      .strict(),
+    wake_payload: z
+      .object({
+        policy: z.enum(["none", "cursor_reason_counts_only", "bounded_redacted_window"]),
+        may_include_message_content: z.boolean().default(false),
+        max_events: z.number().int().positive().max(200).optional(),
+      })
+      .strict()
+      .superRefine((payload, ctx) => {
+        if (payload.policy === "cursor_reason_counts_only" && payload.may_include_message_content) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["may_include_message_content"],
+            message: "cursor/reason wake payloads must not include message content.",
+          });
+        }
+      }),
+    audit: z
+      .object({
+        durable_receipt_required: z.literal(true),
+        idempotency_key_fields: z.array(z.string().min(1)).min(1),
+      })
+      .strict(),
+    runner_lifecycle: z
+      .object({
+        requires_scoped_runner_token: z.literal(true),
+        revoke_token_on_idle_teardown: z.literal(true),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+const hostedSessionConnectorContractSchema = z
+  .object({
+    version: z
+      .literal(HOSTED_SENTI_SESSION_CONNECTOR_CONTRACT_SCHEMA_VERSION)
+      .default(HOSTED_SENTI_SESSION_CONNECTOR_CONTRACT_SCHEMA_VERSION),
+    provider: z.literal("sentinelayer"),
+    connector: z.literal("hosted-senti-session"),
+    generated_at: z.string().min(1),
+    local_registry_file: z.string().min(1),
+    runtime_status: z.literal("contract_only"),
+    boundary: z
+      .object({
+        transport: z.literal("https_mcp_streamable_http"),
+        identity_source: z.literal("validated_oauth_claims_and_server_session_seat"),
+        local_stdio_registry_is_not_hosted_capability: z.literal(true),
+        long_lived_cli_token_passthrough_allowed: z.literal(false),
+      })
+      .strict(),
+    tools: z.array(hostedSessionConnectorToolSchema).min(1),
+    release_gates: z.array(z.string().min(1)).min(1),
+  })
+  .strict();
+
+const REQUIRED_HOSTED_SESSION_CONNECTOR_RELEASE_GATES = [
+  "oauth_resource_binding",
+  "session_seat_ownership",
+  "deny_identity_from_tool_args",
+  "approval_policy_enforcement",
+  "scoped_runner_token_revocation",
+  "wake_payload_minimization",
+  "durable_audit_receipts",
+  "output_redaction",
+  "omar_gate_mcp_security_pack",
+];
+
 const mcpServerTransportSchema = z.discriminatedUnion("mode", [
   z
     .object({
@@ -812,6 +921,152 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
   };
 }
 
+function hostedSessionTool({
+  toolName,
+  operation,
+  allowedUserArgs,
+  requiredScopes,
+  wakePayload = { policy: "none", may_include_message_content: false },
+  runnerLifecycle = null,
+}) {
+  const tool = {
+    tool_name: toolName,
+    local_tool_name: toolName,
+    operation,
+    input_policy: {
+      identity_source: "server_session_seat",
+      rejects_identity_from_tool_args: true,
+      allowed_user_args: allowedUserArgs,
+      forbidden_capability_args: ["sessionId", "session_id", "agentId", "agent_id", "userId", "user_id", "orgId", "org_id"],
+    },
+    authorization: {
+      requires_validated_claims: true,
+      requires_session_seat: true,
+      required_scopes: requiredScopes,
+    },
+    wake_payload: wakePayload,
+    audit: {
+      durable_receipt_required: true,
+      idempotency_key_fields: ["subject", "session_seat", "tool_name", "normalized_inputs"],
+    },
+  };
+  if (runnerLifecycle) {
+    tool.runner_lifecycle = runnerLifecycle;
+  }
+  return tool;
+}
+
+/**
+ * Create the hosted Senti session connector contract.
+ *
+ * This is intentionally separate from the local stdio session registry. Local
+ * tools need sessionId/agentId arguments; hosted tools must derive identity from
+ * validated OAuth claims plus a server-side session seat and must not treat those
+ * arguments as capabilities.
+ *
+ * @param {{ generatedAt?: string, localRegistryFile?: string }} [options]
+ * @returns {Record<string, any>}
+ */
+export function buildHostedSentiSessionConnectorContract({
+  generatedAt = new Date().toISOString(),
+  localRegistryFile = ".sentinelayer/mcp/tool-registry.session-tools.json",
+} = {}) {
+  return {
+    version: HOSTED_SENTI_SESSION_CONNECTOR_CONTRACT_SCHEMA_VERSION,
+    provider: "sentinelayer",
+    connector: "hosted-senti-session",
+    generated_at: generatedAt,
+    local_registry_file: String(localRegistryFile || "").trim() || ".sentinelayer/mcp/tool-registry.session-tools.json",
+    runtime_status: "contract_only",
+    boundary: {
+      transport: "https_mcp_streamable_http",
+      identity_source: "validated_oauth_claims_and_server_session_seat",
+      local_stdio_registry_is_not_hosted_capability: true,
+      long_lived_cli_token_passthrough_allowed: false,
+    },
+    tools: [
+      hostedSessionTool({
+        toolName: "poll_inbox",
+        operation: "read_history",
+        allowedUserArgs: ["cursor", "limit", "actionLimit", "includeActions"],
+        requiredScopes: ["session:read"],
+        wakePayload: { policy: "bounded_redacted_window", may_include_message_content: true, max_events: 50 },
+      }),
+      hostedSessionTool({
+        toolName: "send_message",
+        operation: "send_message",
+        allowedUserArgs: ["message", "to", "idempotencyKey"],
+        requiredScopes: ["session:write"],
+      }),
+      hostedSessionTool({
+        toolName: "session_action",
+        operation: "session_action",
+        allowedUserArgs: ["actionType", "targetSequenceId", "targetCursor", "targetActionId", "note", "idempotencyKey"],
+        requiredScopes: ["session:write", "session:action"],
+      }),
+      hostedSessionTool({
+        toolName: "session_react",
+        operation: "session_action",
+        allowedUserArgs: ["reaction", "targetSequenceId", "targetCursor", "targetActionId", "idempotencyKey"],
+        requiredScopes: ["session:write", "session:action"],
+      }),
+      hostedSessionTool({
+        toolName: "session_reply",
+        operation: "session_action",
+        allowedUserArgs: ["targetSequenceId", "targetCursor", "targetActionId", "message", "idempotencyKey"],
+        requiredScopes: ["session:write", "session:action"],
+      }),
+      hostedSessionTool({
+        toolName: "session_lock",
+        operation: "session_lock",
+        allowedUserArgs: ["files", "intent", "ttlSeconds"],
+        requiredScopes: ["session:lock"],
+      }),
+      hostedSessionTool({
+        toolName: "session_unlock",
+        operation: "session_unlock",
+        allowedUserArgs: ["files", "reason"],
+        requiredScopes: ["session:lock"],
+      }),
+      hostedSessionTool({
+        toolName: "session_locks",
+        operation: "list_locks",
+        allowedUserArgs: [],
+        requiredScopes: ["session:lock"],
+      }),
+      hostedSessionTool({
+        toolName: "attention_request",
+        operation: "attention_request",
+        allowedUserArgs: ["message", "to", "priority", "severity", "idempotencyKey"],
+        requiredScopes: ["session:write"],
+        wakePayload: { policy: "cursor_reason_counts_only", may_include_message_content: false },
+      }),
+      hostedSessionTool({
+        toolName: "subscribe_wake",
+        operation: "subscribe_wake",
+        allowedUserArgs: ["cadencePreset", "wakeTriggers", "sinceCursor"],
+        requiredScopes: ["session:read", "session:wake"],
+        wakePayload: { policy: "cursor_reason_counts_only", may_include_message_content: false },
+        runnerLifecycle: {
+          requires_scoped_runner_token: true,
+          revoke_token_on_idle_teardown: true,
+        },
+      }),
+    ],
+    release_gates: [
+      "oauth_resource_binding",
+      "session_seat_ownership",
+      "deny_identity_from_tool_args",
+      "approval_policy_enforcement",
+      "scoped_runner_token_revocation",
+      "wake_payload_minimization",
+      "durable_audit_receipts",
+      "output_redaction",
+      "omar_gate_mcp_security_pack",
+    ],
+  };
+}
+
 /**
  * Create an AIdenID adapter contract template that binds MCP tools to provisioning endpoints.
  *
@@ -975,6 +1230,68 @@ export function validateAidenIdAdapterContract(payload, { registryPayload } = {}
   return parsed;
 }
 
+/**
+ * Validate and normalize hosted Senti session connector contract payload.
+ * Optionally cross-validates hosted local_tool_name references against a local
+ * session registry payload. Contract-only hosted tools, such as subscribe_wake,
+ * can omit a local registry binding by using the same name as a non-local tool.
+ *
+ * @param {unknown} payload
+ * @param {{ registryPayload?: unknown }} [options]
+ * @returns {any}
+ */
+export function validateHostedSentiSessionConnectorContract(payload, { registryPayload } = {}) {
+  const parsed = hostedSessionConnectorContractSchema.parse(payload);
+  const releaseGateSet = new Set(parsed.release_gates);
+
+  for (const gate of REQUIRED_HOSTED_SESSION_CONNECTOR_RELEASE_GATES) {
+    if (!releaseGateSet.has(gate)) {
+      throw new Error(`Hosted connector contract is missing required release gate ${gate}.`);
+    }
+  }
+
+  for (const tool of parsed.tools) {
+    const forbidden = new Set(tool.input_policy.forbidden_capability_args);
+    for (const key of ["sessionId", "session_id", "agentId", "agent_id"]) {
+      if (!forbidden.has(key)) {
+        throw new Error(`Hosted connector tool ${tool.tool_name} must forbid capability argument ${key}.`);
+      }
+    }
+    for (const arg of tool.input_policy.allowed_user_args) {
+      if (forbidden.has(arg)) {
+        throw new Error(`Hosted connector tool ${tool.tool_name} allows forbidden capability argument ${arg}.`);
+      }
+    }
+    if (tool.operation === "subscribe_wake") {
+      if (!tool.runner_lifecycle) {
+        throw new Error(`Hosted connector tool ${tool.tool_name} must define scoped runner-token lifecycle controls.`);
+      }
+      if (!tool.runner_lifecycle.requires_scoped_runner_token) {
+        throw new Error(`Hosted connector tool ${tool.tool_name} must require a scoped runner token.`);
+      }
+      if (!tool.runner_lifecycle.revoke_token_on_idle_teardown) {
+        throw new Error(`Hosted connector tool ${tool.tool_name} must revoke runner tokens on idle teardown.`);
+      }
+    }
+  }
+
+  if (registryPayload !== undefined) {
+    const registry = validateMcpToolRegistry(registryPayload);
+    const localToolNames = new Set(registry.tools.map((tool) => tool.name));
+    const missingLocalTools = parsed.tools
+      .filter((tool) => tool.operation !== "subscribe_wake" && tool.operation !== "presence_renew" && tool.operation !== "runner_teardown")
+      .map((tool) => tool.local_tool_name)
+      .filter((toolName) => !localToolNames.has(toolName));
+    if (missingLocalTools.length > 0) {
+      throw new Error(
+        `Hosted connector references local tools not present in registry: ${[...new Set(missingLocalTools)].join(", ")}`
+      );
+    }
+  }
+
+  return parsed;
+}
+
 /**
  * Validate and normalize MCP server runtime config payload.
  *
@@ -1069,6 +1386,21 @@ export async function resolveDefaultAidenIdAdapterContractPath({ cwd, outputDir,
   return path.join(outputRoot, "mcp", "aidenid-provisioning-adapter.json");
 }
 
+/**
+ * Resolve default output path for hosted Senti session connector contracts.
+ *
+ * @param {{ cwd?: string, outputDir?: string, env?: NodeJS.ProcessEnv }} [options]
+ * @returns {Promise<string>}
+ */
+export async function resolveDefaultHostedSentiSessionConnectorContractPath({ cwd, outputDir, env } = {}) {
+  const outputRoot = await resolveOutputRoot({
+    cwd,
+    outputDirOverride: outputDir,
+    env,
+  });
+  return path.join(outputRoot, "mcp", "hosted-senti-session-connector.json");
+}
+
 /**
  * Resolve default MCP server config output path for a specific server id.
  *

package/src/review/persona-prompts.js

@@ -72,6 +72,12 @@ MCP / agent-security (clearance-layer specific):
 - Agent sandbox / microVM handed a long-lived or user credential instead of a short-lived, narrowly-scoped, per-session token; secrets injected via env or baked into a VM image/snapshot
 - Sandbox egress not default-denied, or the cloud metadata endpoint (169.254.169.254 / IMDS) reachable from guest code
 - VM memory snapshot reused across sessions or tenants (entropy/RNG/credential bleed)
+- Hosted/bridge tool execution without SERVER-SIDE approval enforcement: requires_human_approval/scopes/kill_switch trusted from client-supplied metadata or skipped, or destructive tools (auth/config/session-kill/file-write/network-scan) runnable with no approval gate (must deny-by-default when policy metadata is missing or malformed)
+- Token-like values UNREDACTED in tool output: stdout/stderr/parsed JSON/command echo/error messages returning bearer tokens, API keys, private keys, OTPs, session cookies, or local auth-store paths to the client or into stored artifacts
+- Blind unpinned @latest CLI/dependency install inside a hosted runner, not resolved to an immutable version with checksum/signature/attestation verification (supply-chain RCE into every spawned VM)
+- Notification/subscribe authorization derived from a sessionId (or other tool arg) instead of the caller's validated claims + server-side session membership (a sessionId is not a capability)
+- Wake/notification payloads exposing message content or PII outside the subscriber's authorized scope (prefer counts/cursors/reasons; redact embedded content per scope)
+- Idle teardown that kills the runner without revoking its scoped token, or session artifacts written by the guest/runner instead of by the control-plane under the owner's account
 
 Evidence standard: Every finding MUST include file:line, exploit scenario, and remediation.
 Do NOT report hypothetical issues without concrete code evidence.`,

package/src/session/remote-hydrate.js

@@ -67,11 +67,18 @@ async function readExistingRelayState(sessionId, { targetPath = process.cwd() }
   const knownKeys = new Set();
   const events = await readStream(sessionId, { targetPath, tail: 0 }).catch(() => []);
   const indexByKey = new Map();
+  const duplicateKeys = new Set();
   for (const [index, event] of events.entries()) {
+    for (const key of sessionEventIdentityKeys(event)) {
+      const existingIndex = indexByKey.get(key);
+      if (Number.isInteger(existingIndex) && existingIndex >= 0 && existingIndex !== index) {
+        duplicateKeys.add(key);
+      }
+    }
     addSessionEventIdentityKeys(knownKeys, event);
     indexRelayEventIdentityKeys(indexByKey, events, event, index);
   }
-  return { knownKeys, events, indexByKey };
+  return { knownKeys, events, indexByKey, duplicateKeys };
 }
 
 async function ensureLocalSessionShell(sessionId, { targetPath = process.cwd() } = {}) {
@@ -380,13 +387,19 @@ export async function hydrateSessionFromRemote({
   const successfulRelayKeys = relayState.knownKeys;
   const existingRelayEvents = relayState.events;
   const existingRelayIndexByKey = relayState.indexByKey;
+  const duplicateRelayKeys = relayState.duplicateKeys || new Set();
   const newEvents = [];
+  const eventsNeedingMerge = new Set();
   for (const event of merged) {
     const existingIndex = findRelayEventIdentityIndex(existingRelayIndexByKey, event);
     if (existingIndex >= 0) {
       const existing = existingRelayEvents[existingIndex];
-      if (sessionEventUpgradesExisting(existing, event)) {
+      if (
+        sessionEventUpgradesExisting(existing, event) ||
+        sessionEventHasKnownIdentity(event, duplicateRelayKeys)
+      ) {
         newEvents.push(event);
+        eventsNeedingMerge.add(event);
       }
       continue;
     }
@@ -416,14 +429,20 @@ export async function hydrateSessionFromRemote({
     }
   }
 
-  const appendEvents =
-    remoteStatus && !["active", "pending"].includes(remoteStatus)
-      ? materialNewEvents.map((event) => markPostKillEvent(event))
-      : materialNewEvents;
+  const appendEvents = materialNewEvents.map((event) => ({
+    event: remoteStatus && !["active", "pending"].includes(remoteStatus)
+      ? markPostKillEvent(event)
+      : event,
+    mergeExisting: eventsNeedingMerge.has(event),
+  }));
   const failedRelayKeys = new Set();
-  for (const event of appendEvents) {
+  for (const { event, mergeExisting } of appendEvents) {
     try {
-      const persisted = await _append(sessionId, event, { targetPath, syncRemote: false });
+      const persisted = await _append(sessionId, event, {
+        targetPath,
+        syncRemote: false,
+        mergeExisting,
+      });
       relayed += 1;
       const persistedEvent = persisted && typeof persisted === "object" ? persisted : event;
       existingRelayEvents.push(persistedEvent);

package/src/session/stream.js

@@ -3,6 +3,10 @@ import process from "node:process";
 import { setTimeout as sleep } from "node:timers/promises";
 
 import { createAgentEvent, normalizeAgentEvent } from "../events/schema.js";
+import {
+  dedupeSessionEvents,
+  sessionEventIdentityKeys,
+} from "./event-identity.js";
 import { enrichEventWithMentions } from "./mentions.js";
 import { resolveSessionPaths } from "./paths.js";
 import { redactEventPayload } from "./redact.js";
@@ -348,6 +352,58 @@ async function rotateStreamIfNeeded(paths, maxEvents) {
   await fsp.writeFile(paths.streamPath, retainedPayload, "utf-8");
 }
 
+function eventsShareIdentity(left = {}, right = {}) {
+  const leftKeys = new Set(sessionEventIdentityKeys(left));
+  if (leftKeys.size === 0) return false;
+  return sessionEventIdentityKeys(right).some((key) => leftKeys.has(key));
+}
+
+async function appendOrMergeCurrentStreamEvent(paths, canonicalEvent, { mergeExisting = false } = {}) {
+  if (!mergeExisting) {
+    await fsp.appendFile(paths.streamPath, `${JSON.stringify(canonicalEvent)}\n`, "utf-8");
+    return;
+  }
+
+  const currentEvents = await readEventsFromFile(paths.streamPath);
+  const matchingIndexes = [];
+  for (const [index, event] of currentEvents.entries()) {
+    if (eventsShareIdentity(event, canonicalEvent)) {
+      matchingIndexes.push(index);
+    }
+  }
+
+  if (matchingIndexes.length === 0) {
+    await fsp.appendFile(paths.streamPath, `${JSON.stringify(canonicalEvent)}\n`, "utf-8");
+    return;
+  }
+
+  const replacement = dedupeSessionEvents([
+    ...matchingIndexes.map((index) => currentEvents[index]),
+    canonicalEvent,
+  ])[0] || canonicalEvent;
+  const firstMatch = matchingIndexes[0];
+  const matchingIndexSet = new Set(matchingIndexes);
+  const mergedEvents = [];
+  for (const [index, event] of currentEvents.entries()) {
+    if (index === firstMatch) {
+      mergedEvents.push(replacement);
+      continue;
+    }
+    if (matchingIndexSet.has(index)) {
+      continue;
+    }
+    mergedEvents.push(event);
+  }
+
+  await fsp.writeFile(
+    paths.streamPath,
+    mergedEvents.length > 0
+      ? `${mergedEvents.map((event) => JSON.stringify(event)).join("\n")}\n`
+      : "",
+    "utf-8",
+  );
+}
+
 function filterBySince(events = [], since) {
   const normalizedSince = normalizeString(since);
   if (!normalizedSince) {
@@ -371,6 +427,7 @@ export async function appendToStream(
     maxEvents = DEFAULT_MAX_STREAM_EVENTS,
     syncRemote = true,
     awaitRemoteSync = false,
+    mergeExisting = false,
   } = {}
 ) {
   const paths = resolveSessionPaths(sessionId, { targetPath });
@@ -403,7 +460,7 @@ export async function appendToStream(
   await acquireLock(paths.lockPath);
   try {
     await fsp.mkdir(paths.sessionDir, { recursive: true });
-    await fsp.appendFile(paths.streamPath, `${JSON.stringify(canonicalEvent)}\n`, "utf-8");
+    await appendOrMergeCurrentStreamEvent(paths, canonicalEvent, { mergeExisting });
     await rotateStreamIfNeeded(paths, normalizedMaxEvents);
 
     metadata.lastInteractionAt = nowIso;