@xemahq/kernel-contracts 0.41.0 → 0.43.0

package/src/ingestion-source/lib/ingestion-source-contribution.ts

@@ -0,0 +1,238 @@
+import { z } from 'zod';
+
+/**
+ * Maximum length of the short identifier / label / tag strings on an ingestion
+ * source manifest. Bounded so list/describe responses stay small and persisted
+ * rows have a predictable upper size.
+ */
+const INGESTION_SOURCE_STRING_MAX = 200;
+
+/**
+ * Maximum length of the free-text summary. A summary is a one-liner, not a
+ * document.
+ */
+const INGESTION_SOURCE_SUMMARY_MAX = 1000;
+
+/**
+ * Maximum length of a fetch URL / cadence expression / record selector — each
+ * is a small path/pattern, never a document.
+ */
+const INGESTION_SOURCE_URL_MAX = 2000;
+const INGESTION_SOURCE_EXPRESSION_MAX = 200;
+const INGESTION_SOURCE_SELECTOR_MAX = 500;
+
+/** Hard cap on the number of static request headers a source may declare. */
+const INGESTION_SOURCE_HEADERS_MAX = 50;
+
+/**
+ * HTTP method used to pull from an ingestion source. Closed set — a source
+ * either GETs a resource or POSTs a query body.
+ */
+export enum IngestionFetchMethod {
+  GET = 'GET',
+  POST = 'POST',
+}
+
+export const INGESTION_FETCH_METHOD_VALUES: readonly IngestionFetchMethod[] = [
+  IngestionFetchMethod.GET,
+  IngestionFetchMethod.POST,
+];
+
+export const IngestionFetchMethodSchema = z.enum(
+  INGESTION_FETCH_METHOD_VALUES as readonly [
+    IngestionFetchMethod,
+    ...IngestionFetchMethod[],
+  ],
+);
+
+/**
+ * How the pull cadence is expressed. Closed set: a fixed interval or a cron
+ * expression. The `expression` field carries the concrete value (a duration
+ * string for `interval`, a cron string for `cron`).
+ */
+export enum IngestionCadenceKind {
+  INTERVAL = 'interval',
+  CRON = 'cron',
+}
+
+export const INGESTION_CADENCE_KIND_VALUES: readonly IngestionCadenceKind[] = [
+  IngestionCadenceKind.INTERVAL,
+  IngestionCadenceKind.CRON,
+];
+
+export const IngestionCadenceKindSchema = z.enum(
+  INGESTION_CADENCE_KIND_VALUES as readonly [
+    IngestionCadenceKind,
+    ...IngestionCadenceKind[],
+  ],
+);
+
+/**
+ * How the platform decides a pulled resource CHANGED since the last pull.
+ * Closed set — the source declares which signal is authoritative so the puller
+ * never guesses.
+ */
+export enum IngestionChangeDetectionStrategy {
+  /** Compare the HTTP `ETag` response header. */
+  ETAG = 'etag',
+  /** Compare the HTTP `Last-Modified` response header. */
+  LAST_MODIFIED = 'last-modified',
+  /** Hash the fetched body and compare content hashes. */
+  CONTENT_HASH = 'content-hash',
+}
+
+export const INGESTION_CHANGE_DETECTION_STRATEGY_VALUES: readonly IngestionChangeDetectionStrategy[] =
+  [
+    IngestionChangeDetectionStrategy.ETAG,
+    IngestionChangeDetectionStrategy.LAST_MODIFIED,
+    IngestionChangeDetectionStrategy.CONTENT_HASH,
+  ];
+
+export const IngestionChangeDetectionStrategySchema = z.enum(
+  INGESTION_CHANGE_DETECTION_STRATEGY_VALUES as readonly [
+    IngestionChangeDetectionStrategy,
+    ...IngestionChangeDetectionStrategy[],
+  ],
+);
+
+/**
+ * `IngestionFetchSpec` — WHERE the data comes from and HOW to request it. A
+ * plain HTTP pull descriptor: URL, method, and optional static headers. No
+ * credential is carried inline — a private source references a broker-resolved
+ * credential through the platform, never a secret in the manifest.
+ */
+export interface IngestionFetchSpec {
+  /** Absolute URL to pull from. ≤ 2000 chars. */
+  readonly url: string;
+  /** HTTP method. Absent ⇒ `GET`. */
+  readonly method?: IngestionFetchMethod;
+  /** Static request headers (non-secret). Hard-capped at 50 entries. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+export const IngestionFetchSpecSchema: z.ZodType<IngestionFetchSpec> = z.object({
+  url: z.string().min(1).max(INGESTION_SOURCE_URL_MAX),
+  method: IngestionFetchMethodSchema.optional(),
+  headers: z
+    .record(
+      z.string().min(1).max(INGESTION_SOURCE_STRING_MAX),
+      z.string().max(INGESTION_SOURCE_STRING_MAX),
+    )
+    .refine((h) => Object.keys(h).length <= INGESTION_SOURCE_HEADERS_MAX, {
+      message: `at most ${INGESTION_SOURCE_HEADERS_MAX} headers`,
+    })
+    .optional(),
+}) as z.ZodType<IngestionFetchSpec>;
+
+/**
+ * `IngestionCadenceSpec` — HOW OFTEN the source is pulled. `kind` selects the
+ * grammar; `expression` carries the concrete value.
+ */
+export interface IngestionCadenceSpec {
+  readonly kind: IngestionCadenceKind;
+  /** Interval duration (for `interval`) or cron expression (for `cron`). */
+  readonly expression: string;
+}
+
+export const IngestionCadenceSpecSchema: z.ZodType<IngestionCadenceSpec> =
+  z.object({
+    kind: IngestionCadenceKindSchema,
+    expression: z.string().min(1).max(INGESTION_SOURCE_EXPRESSION_MAX),
+  }) as z.ZodType<IngestionCadenceSpec>;
+
+/**
+ * `IngestionChangeDetectionSpec` — HOW the puller decides a resource changed.
+ */
+export interface IngestionChangeDetectionSpec {
+  readonly strategy: IngestionChangeDetectionStrategy;
+}
+
+export const IngestionChangeDetectionSpecSchema: z.ZodType<IngestionChangeDetectionSpec> =
+  z.object({
+    strategy: IngestionChangeDetectionStrategySchema,
+  }) as z.ZodType<IngestionChangeDetectionSpec>;
+
+/**
+ * `IngestionCatalogSpec` — WHERE pulled records land and how they are tagged
+ * for provenance. `targetIndex` is the local catalog/index the records are
+ * written into; `provenanceTag` stamps each record so a downstream reader can
+ * trace it back to this source.
+ */
+export interface IngestionCatalogSpec {
+  /** The local catalog/index pulled records are written into. ≤ 200 chars. */
+  readonly targetIndex: string;
+  /** Provenance tag stamped on every pulled record. ≤ 200 chars. */
+  readonly provenanceTag: string;
+}
+
+export const IngestionCatalogSpecSchema: z.ZodType<IngestionCatalogSpec> =
+  z.object({
+    targetIndex: z.string().min(1).max(INGESTION_SOURCE_STRING_MAX),
+    provenanceTag: z.string().min(1).max(INGESTION_SOURCE_STRING_MAX),
+  }) as z.ZodType<IngestionCatalogSpec>;
+
+/**
+ * Manifest shape carried by every `ContributionKind.IngestionSource` envelope.
+ * One contribution = one PULL-BASED external data source.
+ *
+ * Mirrors `CapabilityContributionManifest` / `SearchTypeContributionManifest`
+ * precisely: a value-identical subset of the wire body the owning ingestion
+ * service accepts, validated fail-fast at biome-discovery time. Provenance
+ * (`biome.id`, `biome.version`) is NOT a field here — the parser stamps it from
+ * the discovering biome's `xema-biome.json`. Authors do not declare provenance
+ * inline.
+ *
+ * The descriptor is pure DATA: it declares WHERE the data comes from
+ * (`fetch`), HOW OFTEN to pull it (`cadence`), HOW to detect change
+ * (`changeDetection`), WHERE records land (`catalog`), and OPTIONALLY how to
+ * extract records from the fetched body (`recordSelector`). It never carries
+ * transform/mint code and never carries a secret.
+ *
+ * Validation is fail-fast: a contribution that violates any constraint is
+ * rejected at boot. No silent coercion.
+ */
+export interface IngestionSourceContributionManifest {
+  /** Stable identifier for this source within its owning biome. ≤ 200 chars. */
+  readonly sourceKey: string;
+  /** Human-readable source title. ≤ 200 chars. */
+  readonly title: string;
+  /** Optional one-line summary. ≤ 1000 chars. */
+  readonly summary?: string;
+  /** WHERE the data comes from and HOW to request it. */
+  readonly fetch: IngestionFetchSpec;
+  /** HOW OFTEN the source is pulled. */
+  readonly cadence: IngestionCadenceSpec;
+  /** HOW the puller decides a resource changed since the last pull. */
+  readonly changeDetection: IngestionChangeDetectionSpec;
+  /** WHERE pulled records land and how they are tagged for provenance. */
+  readonly catalog: IngestionCatalogSpec;
+  /**
+   * Optional JSONPath-ish selector applied to the fetched body to extract the
+   * record array. Absent ⇒ the whole body is treated as a single record.
+   * ≤ 500 chars.
+   */
+  readonly recordSelector?: string;
+}
+
+/**
+ * Zod validator for `IngestionSourceContributionManifest`. The biome-discovery
+ * parser AND the owning ingestion service's contribution-sync handler BOTH
+ * route every candidate envelope through this schema, so a malformed
+ * contribution fails at the boundary instead of at the wire (mirrors
+ * `CapabilityContributionManifestSchema`).
+ */
+export const IngestionSourceContributionManifestSchema: z.ZodType<IngestionSourceContributionManifest> =
+  z.object({
+    sourceKey: z.string().min(1).max(INGESTION_SOURCE_STRING_MAX),
+    title: z.string().min(1).max(INGESTION_SOURCE_STRING_MAX),
+    summary: z.string().min(1).max(INGESTION_SOURCE_SUMMARY_MAX).optional(),
+    fetch: IngestionFetchSpecSchema,
+    cadence: IngestionCadenceSpecSchema,
+    changeDetection: IngestionChangeDetectionSpecSchema,
+    catalog: IngestionCatalogSpecSchema,
+    recordSelector: z
+      .string()
+      .min(1)
+      .max(INGESTION_SOURCE_SELECTOR_MAX)
+      .optional(),
+  }) as z.ZodType<IngestionSourceContributionManifest>;

package/src/llm-gateway/lib/errors.ts

@@ -77,6 +77,52 @@ export interface LlmGatewayErrorFrame {
   error: LlmGatewayErrorPayload;
 }
 
+/**
+ * Message signatures that identify a context-window overflow when NO typed
+ * {@link LlmGatewayErrorCode} survived to the consumer.
+ *
+ * The authoritative provider-message → code classification lives in
+ * llm-gateway-api's `upstream-error-classifier.ts` (an independent submodule
+ * that cannot import this kernel package). This list is the CONSUMER-side
+ * counterpart: when an agentic runtime (e.g. OpenCode) swallows the gateway's
+ * typed code and re-surfaces only a human-readable string, this is the single
+ * place a consumer recognizes the overflow. Keep the two lists in parity when
+ * a new provider phrasing appears.
+ */
+export const CONTEXT_OVERFLOW_MESSAGE_PATTERNS: readonly RegExp[] = [
+  /maximum context length is \d+ tokens/i,
+  /input length and max_tokens exceed context limit/i,
+  /context_length_exceeded/i,
+  /context window/i,
+  /prompt is too long/i,
+  /reduce the length of (?:the )?messages/i,
+  /exceed(?:s|ed)?\b[^.]{0,40}\bcontext/i,
+];
+
+/**
+ * Deterministically decide whether an error signal is a context-window
+ * overflow — the single well-named predicate every consumer uses instead of
+ * an ad-hoc string match. Prefers the TYPED code
+ * ({@link LlmGatewayErrorCode.CONTEXT_LENGTH_EXCEEDED}); falls back to the
+ * centralized {@link CONTEXT_OVERFLOW_MESSAGE_PATTERNS} ONLY when the code did
+ * not survive to the consumer (e.g. a runtime that forwards a raw message).
+ *
+ * Passing NEITHER a code nor a message returns `false` — never a silent true.
+ */
+export function isContextOverflowError(input: {
+  code?: string | null;
+  message?: string | null;
+}): boolean {
+  if (input.code === LlmGatewayErrorCode.CONTEXT_LENGTH_EXCEEDED) {
+    return true;
+  }
+  const message = input.message;
+  if (typeof message !== 'string' || message.length === 0) {
+    return false;
+  }
+  return CONTEXT_OVERFLOW_MESSAGE_PATTERNS.some((p) => p.test(message));
+}
+
 /**
  * Type guard for {@link LlmGatewayErrorFrame}.
  */

package/src/output/index.ts

@@ -13,6 +13,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 
 export * from './lib/output-kind';
+export * from './lib/point-of-attention';
 export * from './lib/output-render-hint';
 export * from './lib/output-deliverable-expectation';
 export * from './lib/output-version-dto';

package/src/output/lib/output-version-dto.ts

@@ -1,3 +1,5 @@
+import type { PointOfAttention } from './point-of-attention';
+
 /**
  * One row in the version history of an output. The Outputs panel
  * renders a dropdown when `versions.length > 1`; clicking a non-current
@@ -18,4 +20,11 @@ export interface OutputVersionDto {
   readonly producerAgentSlug: string | null;
   /** True when this row is the latest version. Exactly one row has this set. */
   readonly isCurrent: boolean;
+  /**
+   * Generic producer-authored highlights for THIS version — the salient
+   * things a reader should notice (an assumption, a gap, a risk). Optional
+   * extensibility escape hatch so the fixed version schema stays open without
+   * a per-domain field. Absent/empty ⇒ nothing flagged.
+   */
+  readonly pointsOfAttention?: readonly PointOfAttention[];
 }

package/src/output/lib/point-of-attention.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+
+/**
+ * Bounded maxes for the short label / longer detail strings on a point of
+ * attention. Kept small so a version row carrying a handful of them stays a
+ * cheap, list-safe payload.
+ */
+const POINT_OF_ATTENTION_LABEL_MAX = 200;
+const POINT_OF_ATTENTION_DETAIL_MAX = 2000;
+
+/**
+ * Severity of a {@link PointOfAttention}. Closed set — a consumer renders each
+ * value with a fixed badge/colour, so the domain must never be a free-form
+ * string.
+ */
+export enum PointOfAttentionSeverity {
+  /** Neutral highlight — worth surfacing, no action implied. */
+  INFO = 'info',
+  /** Something the reader should scrutinise before relying on the artifact. */
+  WARNING = 'warning',
+  /** A blocking concern — the artifact should not be trusted/acted on as-is. */
+  CRITICAL = 'critical',
+}
+
+export const POINT_OF_ATTENTION_SEVERITY_VALUES: readonly PointOfAttentionSeverity[] =
+  [
+    PointOfAttentionSeverity.INFO,
+    PointOfAttentionSeverity.WARNING,
+    PointOfAttentionSeverity.CRITICAL,
+  ];
+
+/**
+ * Zod schema for {@link PointOfAttentionSeverity}. Built from the enum so the
+ * literal list lives in exactly one place.
+ */
+export const PointOfAttentionSeveritySchema = z.enum(
+  POINT_OF_ATTENTION_SEVERITY_VALUES as readonly [
+    PointOfAttentionSeverity,
+    ...PointOfAttentionSeverity[],
+  ],
+);
+
+/**
+ * A GENERIC "point of attention" / highlight attached to a per-version
+ * artifact. This is the deliberate extensibility escape hatch that keeps a
+ * fixed artifact schema open: a producer can flag the salient things a reader
+ * should notice (an assumption made, a gap, a risk) WITHOUT the kernel growing
+ * a domain-specific field for each. Domain-agnostic — carries only a label, a
+ * detail, and a {@link PointOfAttentionSeverity}; the meaning is the
+ * producer's, never the kernel's.
+ */
+export interface PointOfAttention {
+  /** Short headline for the point (≤ 200 chars). */
+  readonly label: string;
+  /** Longer human-readable explanation (≤ 2000 chars). */
+  readonly detail: string;
+  /** How much scrutiny this point warrants. */
+  readonly severity: PointOfAttentionSeverity;
+}
+
+/**
+ * Zod validator for {@link PointOfAttention}. Fail-fast: a malformed point is
+ * rejected at the boundary rather than silently coerced.
+ */
+export const PointOfAttentionSchema: z.ZodType<PointOfAttention> = z.object({
+  label: z.string().min(1).max(POINT_OF_ATTENTION_LABEL_MAX),
+  detail: z.string().min(1).max(POINT_OF_ATTENTION_DETAIL_MAX),
+  severity: PointOfAttentionSeveritySchema,
+}) as z.ZodType<PointOfAttention>;

package/src/worker-runtime/index.ts

@@ -12,4 +12,5 @@ export * from './lib/capabilities';
 export * from './lib/messages';
 export * from './lib/runtime';
 export * from './lib/runtime-layout-profile';
+export * from './lib/workspace-sandbox';
 export * from './lib/schemas';

package/src/worker-runtime/lib/enums.ts

@@ -26,6 +26,35 @@ export enum WorkerRuntimeKind {
   Hermes = 'hermes',
 }
 
+/**
+ * How a runtime consumes a per-skill "slash command" launcher file, if at
+ * all. Closed set — a runtime that grows a new command surface adds a member
+ * here and the composer/proxy switch exhaustively on it.
+ *
+ * The platform composes ONE per-skill launch command (markdown body with a
+ * `$ARGUMENTS` placeholder) so typing `/<skill>` loads + applies that skill.
+ * WHETHER and in WHICH FORMAT a runtime reads that file differs:
+ *
+ * - `Markdown` — the runtime reads markdown command files from its
+ *   `commandsDir` (OpenCode: `.opencode/{command,commands}/**.md`; Claude
+ *   Code: `.claude/commands/*.md`). Xema emits the launcher for these.
+ * - `Toml` — the runtime's custom commands are TOML, NOT markdown (Qwen).
+ *   Xema does NOT synthesise TOML skill launchers — skills launch via the
+ *   runtime's own `/skills <name>` surface / model-invoked skill tool — so
+ *   the platform emits NOTHING for a TOML runtime rather than a file the
+ *   runtime silently ignores.
+ * - `None` — the runtime has no file-based slash-command surface at all
+ *   (Hermes: `commandsDir` is `null`). Emit nothing.
+ *
+ * Only `Markdown` runtimes receive a materialised per-skill command file;
+ * `Toml`/`None` receive none (never a stray, silently-ignored file).
+ */
+export enum RuntimeCommandFormat {
+  Markdown = 'markdown',
+  Toml = 'toml',
+  None = 'none',
+}
+
 /**
  * Lifecycle hook surfaces that a runtime may support. The set is closed —
  * adding a new hook is a kernel change.

package/src/worker-runtime/lib/runtime-layout-profile.ts

@@ -20,7 +20,7 @@
 // is where the platform renders the system overlay per WS7.
 // ═══════════════════════════════════════════════════════════════════════════
 
-import { WorkerRuntimeKind } from './enums';
+import { RuntimeCommandFormat, WorkerRuntimeKind } from './enums';
 
 /**
  * The workspace slots whose on-disk location differs per orchestrator. The
@@ -48,6 +48,43 @@ export interface RuntimeLayoutProfile {
    * fail-fast contract as `agentBundlesDir`.
    */
   readonly commandsDir: string | null;
+  /**
+   * How this runtime consumes a per-skill `/`-launch command — the capability
+   * the composer/proxy switch on to decide WHETHER (and in which format) to
+   * materialise a launcher file. `Markdown` runtimes get a launcher written at
+   * `commandsDir`; `Toml`/`None` runtimes get NOTHING (skills still mount as
+   * bundles and launch via the runtime's own `/skills` surface / skill tool),
+   * so no stray file lands where the runtime would silently ignore it.
+   *
+   * INVARIANT: `commandFormat === Markdown` ⟺ `commandsDir !== null`. A runtime
+   * with no command surface (`commandsDir: null`) MUST declare `None`.
+   */
+  readonly commandFormat: RuntimeCommandFormat;
+  /**
+   * Absolute path to the runtime's PRIMARY config file — the file the
+   * orchestrator's bundle composer renders and the supervisor materialises on
+   * the PVC. It carries the LLM-gateway credential (OpenCode reads
+   * `.opencode/opencode.jsonc`; Qwen `.qwen/settings.json` → `env.OPENAI_API_KEY`;
+   * Claude `.claude/settings.json` → `env.ANTHROPIC_AUTH_TOKEN`; Hermes
+   * `.hermes/config.json` → `provider.api_key`) and/or merged MCP bearer headers.
+   *
+   * This is the single source of truth for the config-file location: both the
+   * proxy's on-disk layout and the workspace-sandbox protected-path contract
+   * (`deriveWorkspaceSandboxProtection`) source it here rather than each
+   * re-deriving a per-runtime basename literal.
+   */
+  readonly runtimeConfigFile: string;
+  /**
+   * Absolute path to a DEDICATED MCP-server file the runtime reads separately
+   * from its primary config (Claude Code: `.mcp.json` at the workspace root),
+   * or `null` when the runtime merges MCP into {@link runtimeConfigFile}
+   * (OpenCode/Qwen/Hermes: `InConfig`). When non-null the file carries per-server
+   * bearer headers and is therefore part of the secret read-deny set.
+   *
+   * INVARIANT: `mcpConfigFile !== null` ⟺ the runtime places MCP in a separate
+   * file. A runtime that folds MCP into its primary config MUST declare `null`.
+   */
+  readonly mcpConfigFile: string | null;
 }
 
 /**
@@ -63,6 +100,11 @@ export const RUNTIME_LAYOUT_PROFILES: Readonly<
     contextFile: '/workspace/AGENTS.md',
     agentBundlesDir: '/workspace/.opencode/agents',
     commandsDir: '/workspace/.opencode/command',
+    // OpenCode reads markdown commands from `{command,commands}/**.md`.
+    commandFormat: RuntimeCommandFormat.Markdown,
+    runtimeConfigFile: '/workspace/.opencode/opencode.jsonc',
+    // OpenCode pre-merges MCP into opencode.jsonc (`InConfig`) — no separate file.
+    mcpConfigFile: null,
   },
   [WorkerRuntimeKind.Qwen]: {
     kind: WorkerRuntimeKind.Qwen,
@@ -70,6 +112,13 @@ export const RUNTIME_LAYOUT_PROFILES: Readonly<
     contextFile: '/workspace/AGENTS.md',
     agentBundlesDir: '/workspace/.qwen/agents',
     commandsDir: '/workspace/.qwen/commands',
+    // Qwen custom commands are TOML, not markdown; skills launch via Qwen's
+    // own `/skills <name>` surface. A synthesised markdown `.md` under
+    // `.qwen/commands` would be silently ignored — so Xema emits NOTHING.
+    commandFormat: RuntimeCommandFormat.Toml,
+    runtimeConfigFile: '/workspace/.qwen/settings.json',
+    // Qwen reads its `mcpServers` map INSIDE `.qwen/settings.json` (`InConfig`).
+    mcpConfigFile: null,
   },
   [WorkerRuntimeKind.ClaudeCode]: {
     kind: WorkerRuntimeKind.ClaudeCode,
@@ -77,6 +126,12 @@ export const RUNTIME_LAYOUT_PROFILES: Readonly<
     contextFile: '/workspace/CLAUDE.md',
     agentBundlesDir: '/workspace/.claude/agents',
     commandsDir: '/workspace/.claude/commands',
+    // Claude Code custom slash-commands ARE markdown, under `.claude/commands`.
+    commandFormat: RuntimeCommandFormat.Markdown,
+    runtimeConfigFile: '/workspace/.claude/settings.json',
+    // Claude Code reads project-scoped MCP from a DEDICATED `.mcp.json` at the
+    // workspace root (SeparateFile) — NOT from `.claude/settings.json`.
+    mcpConfigFile: '/workspace/.mcp.json',
   },
   [WorkerRuntimeKind.Hermes]: {
     kind: WorkerRuntimeKind.Hermes,
@@ -89,6 +144,11 @@ export const RUNTIME_LAYOUT_PROFILES: Readonly<
     // is a portable `.md` surface, so the composer must not mount them as files.
     agentBundlesDir: null,
     commandsDir: null,
+    // No file-based slash-command surface at all — emit nothing.
+    commandFormat: RuntimeCommandFormat.None,
+    runtimeConfigFile: '/workspace/.hermes/config.json',
+    // Hermes reads its `mcpServers` map INSIDE `.hermes/config.json` (`InConfig`).
+    mcpConfigFile: null,
   },
 };
 

package/src/worker-runtime/lib/workspace-sandbox.ts

@@ -0,0 +1,129 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace-sandbox protection contract ──
+//
+// A FIRST-CLASS, per-runtime security invariant for the agent-workspace sandbox.
+// The agent runs a code CLI (OpenCode/Qwen/Claude/Hermes) inside the workspace
+// pod with its OWN file tools (read/edit/write). Those tools MUST NOT be able to:
+//
+//   (a) READ the mounted platform secrets — the runtime config file carries the
+//       LLM-gateway credential (a signed JWT) and/or merged MCP bearer headers,
+//       and a dedicated `.mcp.json` (Claude) carries per-server bearer headers.
+//   (b) MUTATE the agent's OWN system-instructions / agent-definition bundles —
+//       the auto-loaded context file (`AGENTS.md`/`CLAUDE.md`), the file-based
+//       sub-agent definitions, the Xema-private system overlay + injected
+//       instruction sections, and the `context.json` capability-authority spec
+//       (rewriting it would let the agent self-grant tools).
+//
+// This module DECLARES that protected-path set ONCE, derived from the kernel
+// `RuntimeLayoutProfile` (the SSOT for every per-runtime path). Each runtime's
+// config builder translates the neutral glob set into its NATIVE permission
+// vocabulary (OpenCode `permission.read`/`permission.edit` globs; Claude Code
+// `permissions.deny: ["Read(...)","Edit(...)"]`). Runtimes with no per-file
+// permission surface (Qwen/Hermes) cannot consume the deny set and fall back to
+// the pod's uid + per-org mount confinement — see the residual note in each
+// builder. The contract is declared here regardless so the invariant is
+// single-sourced, not scattered across builders.
+//
+// Globs are runtime-syntax-NEUTRAL absolute paths anchored at `/workspace`
+// (`*` matches any character; `<dir>/**` covers a whole slot). Callers adapt
+// them to their runtime's matcher.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import {
+  WorkspaceMount,
+} from '../../agent-workspace/lib/workspace-layout';
+
+import type { RuntimeLayoutProfile } from './runtime-layout-profile';
+
+/**
+ * The resolved protected-path set for one runtime's workspace sandbox.
+ *
+ * - `secretReadDenyGlobs` — the agent's READ tool must DENY these (secrets). The
+ *   agent may still read its own instructions/code; only credential-bearing
+ *   files are denied.
+ * - `protectedEditDenyGlobs` — the agent's EDIT/WRITE tool must DENY these
+ *   (own system-instructions, agent-definitions, authority spec, and — defense
+ *   in depth — its own credential config). The agent may still edit workspace
+ *   code, deliverables, repos, inputs, uploads, and tmp.
+ *
+ * Every entry is an absolute `/workspace/...` glob. Both sets are de-duplicated
+ * and stable-ordered.
+ */
+export interface WorkspaceSandboxProtection {
+  readonly secretReadDenyGlobs: readonly string[];
+  readonly protectedEditDenyGlobs: readonly string[];
+}
+
+/**
+ * Constant, runtime-AGNOSTIC Xema-private system-instruction + authority slots.
+ * These are excluded from the per-runtime `RuntimeLayoutProfile` on purpose (the
+ * profile only carries the slots whose ON-DISK path differs per runtime), so
+ * they are sourced from the `WorkspaceMount` SSOT here — never re-literalled.
+ *
+ * All are EDIT-denied (never mutate the injected system overlay / instructions /
+ * capability-authority). They are NOT read-denied: the runtime legitimately
+ * loads the overlay + instructions as context, and the plugin reads
+ * `context.json`.
+ */
+const XEMA_PRIVATE_INSTRUCTION_EDIT_GLOBS: readonly string[] = [
+  // /workspace/.xema/system-overlay.md — the injected system prompt overlay.
+  WorkspaceMount.SystemOverlay,
+  // /workspace/.xema/instructions/** — injected rule/policy instruction sections.
+  `${WorkspaceMount.Instructions}/**`,
+  // /workspace/context.json — carries authority.allowedXemaTools; rewriting it
+  // would let the agent escalate its own tool grants.
+  WorkspaceMount.ContextJson,
+];
+
+function dedupeStable(globs: readonly string[]): string[] {
+  return [...new Set(globs)];
+}
+
+/**
+ * Derive the workspace-sandbox protected-path set for a runtime, from its
+ * kernel `RuntimeLayoutProfile`. Pure — no I/O, no defaults that mask input.
+ *
+ * The set is CLOSED and fail-closed: a config file always exists (every runtime
+ * declares `runtimeConfigFile`), and every credential-bearing / instruction path
+ * the profile exposes is protected. A runtime with no file-based sub-agent
+ * surface (`agentBundlesDir === null`, e.g. Hermes) contributes no agent-def
+ * glob — there is no such directory to protect.
+ */
+export function deriveWorkspaceSandboxProtection(
+  profile: RuntimeLayoutProfile,
+): WorkspaceSandboxProtection {
+  const configFile = profile.runtimeConfigFile;
+  const mcpFile = profile.mcpConfigFile;
+
+  // ── (a) Secret READ deny ─────────────────────────────────────────────────
+  // The credential-bearing config file + (if separate) the bearer-header MCP
+  // file. Nothing else is read-denied — the agent must still read its own
+  // instructions + workspace code.
+  const secretReadDenyGlobs: string[] = [configFile];
+  if (mcpFile !== null) {
+    secretReadDenyGlobs.push(mcpFile);
+  }
+
+  // ── (b) Own-instruction / agent-def EDIT deny ────────────────────────────
+  const protectedEditDenyGlobs: string[] = [
+    // The auto-loaded context file (AGENTS.md / CLAUDE.md) IS the agent's own
+    // system instructions.
+    profile.contextFile,
+    // Defense in depth: never let the agent rewrite its own credential config
+    // (e.g. to strip its own deny rules or exfiltrate the token).
+    configFile,
+    ...XEMA_PRIVATE_INSTRUCTION_EDIT_GLOBS,
+  ];
+  if (mcpFile !== null) {
+    protectedEditDenyGlobs.push(mcpFile);
+  }
+  if (profile.agentBundlesDir !== null) {
+    // The whole file-based sub-agent-definition slot.
+    protectedEditDenyGlobs.push(`${profile.agentBundlesDir}/**`);
+  }
+
+  return {
+    secretReadDenyGlobs: dedupeStable(secretReadDenyGlobs),
+    protectedEditDenyGlobs: dedupeStable(protectedEditDenyGlobs),
+  };
+}

package/src/workflow/index.ts

@@ -8,6 +8,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 
 export * from './lib/enums';
+export * from './lib/workflow-control';
 export * from './lib/temporal-namespace';
 export * from './lib/platform-task-queue';
 export * from './lib/errors';