@kl-c/matrixos 0.1.40 → 0.2.0

package/dist/gateway/gateway-handler.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Gateway message handler.
+ *
+ * Receives a normalized envelope from the MatrixGateway, dispatches to a
+ * MaTrixOS CLI subprocess (default: `matrixos run <text>`), and returns
+ * the agent reply to be sent back through the adapter.
+ *
+ * Why subprocess and not in-process: the agent runtime is OpenCode-driven
+ * and uses its own conversation loop. Forcing it into the gateway's event
+ * loop is an L-scale refactor; subprocess keeps the gateway stateless and
+ * the agent isolated. Each message = fresh agent process, no session
+ * reuse for v0 (Phase 1 limitation, documented in TRACABILITE).
+ */
+import type { UnifiedEnvelope } from "@matrixos/matrix-gateway-core";
+export interface GatewayHandlerOptions {
+    /** Command to invoke. Default: matrixos (resolved via PATH). */
+    readonly command?: string;
+    /** Args to pass (default: ["run", text]). Use {text} as placeholder. */
+    readonly args?: string[];
+    /** Working dir for the subprocess. */
+    readonly cwd?: string;
+    /** Timeout in ms (default 30s). */
+    readonly timeoutMs?: number;
+    /** Env overrides (merged on top of process.env, secrets redacted). */
+    readonly env?: Record<string, string>;
+    /** Optional callback for partial output (Phase 2: streaming). */
+    readonly onPartial?: (chunk: string) => void;
+}
+export interface GatewayHandlerResult {
+    readonly ok: boolean;
+    readonly reply: string;
+    readonly durationMs: number;
+    readonly exitCode: number | null;
+}
+/**
+ * Slash command detection. If the inbound text starts with /adopt, the
+ * handler dispatches to the adoption flow instead of the agent subprocess.
+ * Returns true if the command was handled inline (caller should not run
+ * the subprocess).
+ */
+export declare const ADOPT_COMMAND = "/adopt";
+export declare function isAdoptCommand(env: UnifiedEnvelope): boolean;
+export declare function handleAdoptCommand(env: UnifiedEnvelope, opts?: GatewayHandlerOptions): Promise<GatewayHandlerResult>;
+export declare function handleGatewayMessage(env: UnifiedEnvelope, opts?: GatewayHandlerOptions): Promise<GatewayHandlerResult>;

package/dist/index.js

@@ -368023,7 +368023,7 @@ function getCachedVersion(options = {}) {
 // package.json
 var package_default = {
   name: "@kl-c/matrixos",
-  version: "0.1.40",
+  version: "0.2.0",
   description: "MaTrixOS \u2014 Agentic OS for OpenCode. Personalizable, communicating, self-improving, resilient.",
   main: "./dist/index.js",
   types: "dist/index.d.ts",
@@ -441224,6 +441224,149 @@ async function resolveSessionAgent(client5, sessionId) {
 // packages/omo-opencode/src/plugin/tool-execute-before.ts
 init_constants3();
 init_storage();
+
+// packages/omo-opencode/src/security/validation-guard.ts
+var PATTERNS = [
+  {
+    id: "bash.rm-recursive",
+    description: "Recursively deletes files (rm -rf). Confirm before running.",
+    match: (c) => c.tool.toLowerCase() === "bash" && typeof c.args.command === "string" && /\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r)\b/.test(c.args.command)
+  },
+  {
+    id: "bash.git-force-push",
+    description: "Force-pushes git history. Can destroy remote work.",
+    match: (c) => c.tool.toLowerCase() === "bash" && typeof c.args.command === "string" && /\bgit\s+push\s+(-[a-zA-Z]*f|--force(?!-with-lease))/.test(c.args.command)
+  },
+  {
+    id: "bash.git-reset-hard",
+    description: "git reset --hard destroys uncommitted changes.",
+    match: (c) => c.tool.toLowerCase() === "bash" && typeof c.args.command === "string" && /\bgit\s+reset\s+--hard\b/.test(c.args.command)
+  },
+  {
+    id: "bash.npm-publish",
+    description: "Publishes a package to a public registry. Confirm version + scope.",
+    match: (c) => c.tool.toLowerCase() === "bash" && typeof c.args.command === "string" && /\bnpm\s+publish\b/.test(c.args.command)
+  },
+  {
+    id: "bash.chmod-777",
+    description: "chmod 777 opens the file to everyone. Confirm intent.",
+    match: (c) => c.tool.toLowerCase() === "bash" && typeof c.args.command === "string" && /\bchmod\s+(-[a-zA-Z]*R\s+)?777\b/.test(c.args.command)
+  },
+  {
+    id: "bash.curl-pipe-bash",
+    description: "Pipes a remote script into bash (remote code execution).",
+    match: (c) => c.tool.toLowerCase() === "bash" && typeof c.args.command === "string" && /curl[^|]*\|\s*(sudo\s+)?bash/.test(c.args.command)
+  },
+  {
+    id: "write.env-or-secrets",
+    description: "Writes to a .env / credentials / secrets file.",
+    match: (c) => {
+      if (c.tool.toLowerCase() !== "write" && c.tool.toLowerCase() !== "edit")
+        return false;
+      const path27 = typeof c.args.filePath === "string" ? c.args.filePath : typeof c.args.path === "string" ? c.args.path : "";
+      return /\.env(\.|$)|\/\.klc-secrets\/|\/\.aws\/credentials|id_rsa|id_ed25519/.test(path27);
+    }
+  },
+  {
+    id: "write.system-path",
+    description: "Writes to a system path (/etc/, /usr/, /var/). Confirm intent.",
+    match: (c) => {
+      if (c.tool.toLowerCase() !== "write" && c.tool.toLowerCase() !== "edit")
+        return false;
+      const path27 = typeof c.args.filePath === "string" ? c.args.filePath : typeof c.args.path === "string" ? c.args.path : "";
+      return /^\s*(\/etc\/|\/usr\/|\/var\/)/.test(path27);
+    }
+  }
+];
+function checkValidation(tool3, args) {
+  const call = { tool: tool3, args };
+  for (const p of PATTERNS) {
+    if (p.match(call)) {
+      return {
+        verdict: "deny",
+        reason: `[P-001 Prepare-Never-Submit] Blocked: ${p.description} (pattern: ${p.id}). Ask the user to confirm before running this command.`,
+        pattern: p.id
+      };
+    }
+  }
+  return { verdict: "allow" };
+}
+
+// packages/omo-opencode/src/security/injection-guard.ts
+var INJECTION_PATTERNS = [
+  { id: "ignore-previous", re: /\bignore\s+(all\s+)?(previous|prior|above)\s+(instructions?|directives?|prompts?)/i, description: "ignore previous instructions" },
+  { id: "you-are-now", re: /\byou\s+are\s+now\s+(a|an)\s+/i, description: "you are now a \u2026" },
+  { id: "system-prompt-tag", re: /<\|im_start\|>\s*system|<\|im_end\|>/i, description: "ChatML system tag (model-tag injection)" },
+  { id: "assistant-tag-injection", re: /<\|im_start\|>\s*assistant\b/i, description: "ChatML assistant tag in user content" },
+  { id: "developer-mode", re: /\b(developer|dan|jailbreak|do\s+anything\s+now)\s+mode\b/i, description: "jailbreak mode trigger" },
+  { id: "disregard-safety", re: /\b(disregard|bypass|ignore)\s+(safety|guardrails?|restrictions?|policies)/i, description: "disregard safety guardrails" },
+  { id: "execute-following", re: /\bexecute\s+the\s+following\s+(command|code|instructions?)/i, description: "execute the following \u2026" },
+  { id: "new-instructions", re: /\bnew\s+instructions?:/i, description: "new instructions: header" },
+  { id: "repeat-after-me", re: /\brepeat\s+after\s+me\b/i, description: "repeat after me" },
+  { id: "system-colon-override", re: /^\s*system\s*:\s*[\w]/im, description: "system: override (line-start)" }
+];
+function containsInjection(text) {
+  for (const p of INJECTION_PATTERNS) {
+    const m = p.re.exec(text);
+    if (m) {
+      const start = Math.max(0, m.index - 20);
+      const end = Math.min(text.length, m.index + m[0].length + 20);
+      return { id: p.id, description: p.description, snippet: text.slice(start, end) };
+    }
+  }
+  return null;
+}
+var STRICT_FIELDS = {
+  bash: {
+    command: "string-narrow",
+    timeout: "number"
+  },
+  write: {
+    filePath: "string-strict",
+    content: "string-narrow"
+  },
+  edit: {
+    filePath: "string-strict",
+    oldString: "string-strict",
+    newString: "string-narrow"
+  },
+  read: {
+    filePath: "string-strict"
+  },
+  glob: {
+    pattern: "string-strict"
+  },
+  grep: {
+    pattern: "string-strict",
+    path: "string-strict"
+  }
+};
+var PATH_RE = /^[^\x00-\x1f]*$/;
+var MAX_NARROW = 1e5;
+function sanitizeToolArgs(tool3, args) {
+  const schema2 = STRICT_FIELDS[tool3.toLowerCase()];
+  if (!schema2)
+    return { ok: true };
+  for (const [field, kind] of Object.entries(schema2)) {
+    const v = args[field];
+    if (v === undefined || v === null)
+      continue;
+    if (typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean") {
+      return { ok: false, reason: `field ${field} has wrong type ${typeof v}`, field };
+    }
+    if (typeof v === "string") {
+      if (kind === "string-strict" && !PATH_RE.test(v)) {
+        return { ok: false, reason: `field ${field} contains control characters or is empty`, field };
+      }
+      if (kind === "string-narrow" && v.length > MAX_NARROW) {
+        return { ok: false, reason: `field ${field} too long (${v.length} > ${MAX_NARROW})`, field };
+      }
+    }
+  }
+  return { ok: true };
+}
+
+// packages/omo-opencode/src/plugin/tool-execute-before.ts
 var BACKGROUND_WAIT_BLOCK_MESSAGE = [
   "Background task wait is already managed by the plugin.",
   "End this response now and wait for the <system-reminder> completion notification.",
@@ -441300,6 +441443,27 @@ function createToolExecuteBeforeHandler3(args) {
     if (egressDecision?.verdict === "deny") {
       throw new Error(`Egress blocked: ${egressDecision.reason}`);
     }
+    const validation = checkValidation(input.tool, output.args);
+    if (validation.verdict === "deny") {
+      throw new Error(validation.reason);
+    }
+    const sanitize = sanitizeToolArgs(input.tool, output.args);
+    if (!sanitize.ok) {
+      throw new Error(`[A12 injection-guard] Tool arg rejected: ${sanitize.reason} (field: ${sanitize.field})`);
+    }
+    if (input.tool.toLowerCase() === "bash" && typeof output.args.command === "string") {
+      const inj = containsInjection(output.args.command);
+      if (inj) {
+        log2("[A12 injection-guard] Possible prompt injection in bash command", {
+          sessionID: input.sessionID,
+          callID: input.callID,
+          match: inj
+        });
+        if (output.args.command.includes("MTRX-CANARY-")) {
+          throw new Error(`[A12 injection-guard] Bash command contains canary token \u2014 possible exfiltration attempt. Aborting.`);
+        }
+      }
+    }
     await hooks.writeExistingFileGuard?.["tool.execute.before"]?.(input, output);
     await hooks.notepadWriteGuard?.["tool.execute.before"]?.(input, output);
     await hooks.questionLabelTruncator?.["tool.execute.before"]?.(input, output);

package/dist/observability/progress.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Task Progress Streaming (ANNEXE A17).
+ *
+ * Emits structured progress events for long-running tool calls so the
+ * gateway (or CLI) can display real-time status instead of a silent wait.
+ *
+ * NOTE: today the consumer is the structured log. The Telegram gateway
+ * (CDC §7) is not implemented yet — when it is, it can subscribe to
+ * these events to edit messages in real time. The schema is stable.
+ */
+export type ProgressEvent = {
+    type: "task.progress";
+    taskId: string;
+    tool: string;
+    sessionID: string;
+    callID: string;
+    step: number;
+    totalSteps: number;
+    message: string;
+    startedAt: number;
+    elapsedMs: number;
+};
+type Listener = (e: ProgressEvent) => void;
+/** Subscribe to progress events. Returns an unsubscribe function. */
+export declare function onProgress(listener: Listener): () => void;
+/** Start a task. Returns the taskId. */
+export declare function startTask(tool: string, sessionID: string, callID: string, totalSteps?: number): string;
+/** Advance the current task. */
+export declare function advance(message: string): void;
+/** End the current task. */
+export declare function endTask(message?: string): void;
+/** Run an async operation with task progress tracking. */
+export declare function withProgress<T>(tool: string, sessionID: string, callID: string, op: (advance: (msg: string) => void) => Promise<T>): Promise<T>;
+export {};

package/dist/recovery/checkpoint.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Mid-Task Checkpoint (ANNEXE A9).
+ *
+ * Saves the in-flight task state every 30s so a crash (network, OOM, SIGKILL)
+ * can resume mid-task instead of restarting from scratch.
+ *
+ * Difference from snapshot (CDC §18.7): checkpoint is automatic + granular
+ * (one file, the in-flight task state), snapshot is manual + coarse
+ * (full DB + files).
+ *
+ * Storage: .matrixos/checkpoints/<taskId>.json (last write wins).
+ */
+export type CheckpointState = {
+    taskId: string;
+    tool: string;
+    sessionID: string;
+    startedAt: number;
+    updatedAt: number;
+    step: number;
+    totalSteps: number;
+    history: {
+        tool: string;
+        args: Record<string, unknown>;
+        at: number;
+        ok: boolean;
+    }[];
+    context: Record<string, unknown>;
+};
+/** Start checkpointing a new task. Replaces any prior current task. */
+export declare function startCheckpoint(taskId: string, tool: string, sessionID: string, totalSteps?: number, context?: Record<string, unknown>): void;
+/** Record that a tool call happened. */
+export declare function recordStep(tool: string, args: Record<string, unknown>, ok: boolean): void;
+/** Update free-form context (e.g. current goal, partial results). */
+export declare function updateContext(patch: Record<string, unknown>): void;
+/** Force a flush to disk (in addition to the 30s timer). */
+export declare function flush(): Promise<void>;
+/** Stop the current checkpoint (call when the task completes). */
+export declare function stopCheckpoint(): void;
+/** Read a saved checkpoint by taskId, if it exists. */
+export declare function loadCheckpoint(taskId: string, dir?: string): Promise<CheckpointState | null>;
+/** List all checkpoints (for crash-recovery on session start). */
+export declare function listCheckpoints(dir?: string): Promise<string[]>;

package/dist/resilience/retry.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Graceful Degradation / Retry with Backoff (ANNEXE A14).
+ *
+ * Generic retry wrapper with exponential backoff + jitter.
+ * Used by the model resolver to retry on transient failures
+ * (rate-limit, network blip, 5xx) before falling back to the
+ * next provider in the chain.
+ */
+export type RetryOptions = {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitterRatio: number;
+    shouldRetry: (err: unknown) => boolean;
+};
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: Partial<RetryOptions>): Promise<T>;
+/** Default shouldRetry: retry on transient errors, NOT on validation/programmer errors. */
+export declare function isTransientError(err: unknown): boolean;

package/dist/security/injection-guard.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Prompt Injection Defense (ANNEXE A12).
+ *
+ * Three defense layers applied at the tool boundary:
+ *  1. containsInjection() — detect known prompt-injection patterns in content
+ *     the agent is about to consume (file contents, command output, etc.).
+ *  2. extractCanary() — pull a canary token from the system prompt and let
+ *     checkCanaryInOutput() flag any tool output that contains it (a sign
+ *     that the system prompt was exfiltrated into a tool result).
+ *  3. sanitizeToolArgs() — reject free-form text in tool arg fields that
+ *     should be strictly typed (paths, IDs, enums).
+ */
+export type InjectionMatch = {
+    id: string;
+    description: string;
+    snippet: string;
+};
+/** Returns the first injection match found, or null if clean. */
+export declare function containsInjection(text: string): InjectionMatch | null;
+/** Returns the canary token to embed in the system prompt. */
+export declare function generateCanary(): string;
+/** Returns true if the canary appears in the output (sign of exfiltration). */
+export declare function checkCanaryInOutput(output: string, canary: string): boolean;
+export type SanitizeResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    field: string;
+};
+/** Reject tool args that don't match the strict schema (no control chars in paths, etc.). */
+export declare function sanitizeToolArgs(tool: string, args: Record<string, unknown>): SanitizeResult;

package/dist/security/validation-guard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Prepare-Never-Submit (P-001) — tool-level validation guard.
+ *
+ * Inspired by ANNEXE_A A3. Detects high-risk tool calls BEFORE execution and
+ * throws so the agent sees the error and asks the human to confirm.
+ *
+ * NOTE: The annex proposes a skill-level frontmatter (requires_validation).
+ * The current OpenCode hook system does not expose skill context at the
+ * tool.execute.before layer, so this guard is PATTERN-based on tool + args.
+ * This is less fine-grained but more robust (catches both skill-driven and
+ * ad-hoc risky calls) and applicable today without a hook refactor.
+ */
+export type ToolCall = {
+    tool: string;
+    args: Record<string, unknown>;
+};
+export type ValidationDecision = {
+    verdict: "deny";
+    reason: string;
+    pattern: string;
+} | {
+    verdict: "allow";
+};
+/** Decide whether the tool call needs human validation. Throws nothing — pure decision. */
+export declare function checkValidation(tool: string, args: Record<string, unknown>): ValidationDecision;

package/dist/skills/skill-registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Skill versioning.
+ *
+ * Convention: <root>/<skill-name>/<semver>/SKILL.md
+ * The active version is recorded in <root>/<skill-name>/active (a file
+ * whose content is the version string, e.g. "1.0.0").
+ *
+ * Why: when modifying a skill, the old version is preserved. The active
+ * pointer lets the runtime pick the current version without breaking
+ * the in-flight calls. Rollback = rewrite the active file.
+ */
+export type SkillVersion = {
+    name: string;
+    version: string;
+    path: string;
+};
+export declare class SkillRegistry {
+    private root;
+    constructor(root: string);
+    /** All versions of a skill, newest first. */
+    list(name: string): Promise<SkillVersion[]>;
+    /** List all skills that have at least one versioned SKILL.md. */
+    listAll(): Promise<{
+        name: string;
+        versions: SkillVersion[];
+    }[]>;
+    /** Read the active version (or the latest if no active file). */
+    getActive(name: string): Promise<SkillVersion | null>;
+    /** Set the active version. */
+    setActive(name: string, version: string): Promise<void>;
+    /** Add a new version (mkdir + write SKILL.md content). */
+    addVersion(name: string, version: string, content: string): Promise<SkillVersion>;
+}

package/dist/skills/skill-test-runner.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Skill test runner.
+ *
+ * Convention: a skill may have a co-located <name>.test.ts (or
+ * __tests__/<name>.test.ts) that exercises the skill instructions. The
+ * runner discovers these files, parses the skill frontmatter, and exposes
+ * the metadata to the test as a fixture.
+ *
+ * Usage (CLI):
+ *   matrixos skill test <name>         # run a skill's tests
+ *   matrixos skill test --all          # run all skills' tests
+ *
+ * Usage (programmatic):
+ *   import { runSkillTest, parseSkillFrontmatter } from "./skill-test-runner"
+ */
+export type SkillFrontmatter = {
+    name: string;
+    description: string;
+    triggers: string[];
+    requiresValidation: boolean;
+    raw: Record<string, unknown>;
+};
+export declare function parseSkillFrontmatter(content: string): {
+    frontmatter: SkillFrontmatter;
+    body: string;
+} | null;
+/** Find the test file for a skill. */
+export declare function findSkillTestFile(skillRoot: string, skillName: string): Promise<string | null>;
+/** Run a single skill test (programmatic). Returns a result object. */
+export declare function runSkillTest(skillRoot: string, skillName: string, testFn: (ctx: {
+    skill: SkillFrontmatter;
+    body: string;
+}) => void | Promise<void>): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/** Discover all skills with test files. */
+export declare function discoverSkillTests(skillRoot: string): Promise<{
+    name: string;
+    testFile: string;
+}[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kl-c/matrixos",
-  "version": "0.1.40",
+  "version": "0.2.0",
   "description": "MaTrixOS — Agentic OS for OpenCode. Personalizable, communicating, self-improving, resilient.",
   "main": "./dist/index.js",
   "types": "dist/index.d.ts",