praxis-agent 0.20.0 → 0.20.2

package/README.md

@@ -168,9 +168,20 @@ Praxis ──────┘
 ```
 
 Praxis can resume Claude Code sessions, and Claude Code can resume compatible
-sessions written by Praxis. The validated read-write target is Claude Code
-2.1.208; unknown versions fail closed for transcript writes while retaining
-read-only inspection and export paths.
+sessions written by Praxis. Ordinary Praxis session runtime always emits the
+verified Claude Code 2.1.208 write profile and never derives it from an
+installed Claude version; this fixed profile governs generated append and
+sidechain writes. Native fork creation is a separate restricted lossless copy
+path that preserves each existing source record's producer version, so it can
+copy specific black-box-verified foreign shapes such as the observed Claude
+Code 2.1.233 records; unsupported record shapes and unverified versions still
+fail closed and remain read-only. Maintainers can prove mixed-version Claude JSONL interoperability with
+`npm run test:cross-version-session-compat`, `test:cross-version-fork-compat`,
+`test:cross-version-sidechain-compat`, `test:cross-version-compaction-compat`,
+and `test:cross-version-resume-at-compat`, covering linear resume, native fork,
+foreground sidechain, compaction, and `--resume-session-at` branch projection.
+Each requires `PRAXIS_CLAUDE_BINARY` (Claude Code 2.1.208) and
+`PRAXIS_CLAUDE_CROSS_VERSION_BINARY` (a different Claude Code version).
 
 See the
 [compatibility contract](https://github.com/Forest-Isle/Praxis/blob/main/docs/COMPATIBILITY.md)

package/dist/cli/tui/claude-command-inventory.d.ts

@@ -72,9 +72,8 @@ export declare const CLAUDE_2_1_208_COMMAND_INVENTORY: readonly [{
     readonly visibility: "visible";
 }, {
     readonly name: "doctor";
-    readonly disposition: "required";
+    readonly disposition: "included";
     readonly visibility: "conditional";
-    readonly reason: "Interactive /doctor is required; the top-level command is not a substitute.";
 }, {
     readonly name: "effort";
     readonly disposition: "included";
@@ -254,9 +253,8 @@ export declare const CLAUDE_2_1_208_COMMAND_INVENTORY: readonly [{
     readonly reason: "Claude subscription rate-limit purchasing is outside the authentication boundary.";
 }, {
     readonly name: "usage";
-    readonly disposition: "excluded";
+    readonly disposition: "included";
     readonly visibility: "conditional";
-    readonly reason: "The source command is the Claude subscription plan-usage panel.";
 }, {
     readonly name: "insights";
     readonly disposition: "deferred";

package/dist/cli/tui/claude-command-inventory.js

@@ -38,12 +38,7 @@ export const CLAUDE_2_1_208_COMMAND_INVENTORY = [
         reason: 'The dedicated /cost contract is included; /status is not a substitute.',
     },
     { name: 'diff', disposition: 'included', visibility: 'visible' },
-    {
-        name: 'doctor',
-        disposition: 'required',
-        visibility: 'conditional',
-        reason: 'Interactive /doctor is required; the top-level command is not a substitute.',
-    },
+    { name: 'doctor', disposition: 'included', visibility: 'conditional' },
     { name: 'effort', disposition: 'included', visibility: 'visible' },
     { name: 'exit', disposition: 'included', visibility: 'visible' },
     {
@@ -173,12 +168,7 @@ export const CLAUDE_2_1_208_COMMAND_INVENTORY = [
         visibility: 'hidden',
         reason: 'Claude subscription rate-limit purchasing is outside the authentication boundary.',
     },
-    {
-        name: 'usage',
-        disposition: 'excluded',
-        visibility: 'conditional',
-        reason: 'The source command is the Claude subscription plan-usage panel.',
-    },
+    { name: 'usage', disposition: 'included', visibility: 'conditional' },
     {
         name: 'insights',
         disposition: 'deferred',

package/dist/cli.js

@@ -31,6 +31,7 @@ import { ClaudeMcpToolRegistry, } from './mcp/claude-mcp-tools.js';
 import { ClaudeMcpManagement, filterDisabledMcpResources, mcpScope, } from './mcp/claude-mcp-management.js';
 import { authenticateMcpServer, ClaudeMcpOAuthStore, mcpOAuthServerIdentity, readMcpClientSecret, } from './mcp/claude-mcp-oauth.js';
 import { servePraxisMcpStdio } from './mcp/praxis-mcp-server.js';
+import { VERIFIED_CLAUDE_SCHEMA_VERSION } from './compatibility/claude/schema.js';
 import { detectInstalledClaudeVersion } from './platform/claude-version.js';
 import { redactSensitiveText, sensitiveEnvironmentValues, } from './platform/sensitive-data.js';
 import { AnthropicCompatibleProvider } from './providers/anthropic-compatible.js';
@@ -697,7 +698,7 @@ const consoleIO = {
 const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = false, approveRecovery, approveTool, agent, model: interactiveModel, effort: interactiveEffort, permissionMode: interactivePermissionMode, isSessionActionApproved, controls = DEFAULT_CLI_CONTROLS, interactive = false, sessionKind, signal, exposeToolRegistry = false, onElicitation, askUser, approvePlan, emitToolUseSummaries = false, cwd: requestedCwd, sandboxOriginalCwd, configRoot: requestedConfigRoot, environment, providerEnvironment: requestedProviderEnvironment, }) => {
     const runtimeEnvironment = requestedProviderEnvironment ?? process.env;
     const sandboxEnvironment = { ...runtimeEnvironment, ...environment };
-    const claudeVersion = await detectInstalledClaudeVersion();
+    const claudeVersion = VERIFIED_CLAUDE_SCHEMA_VERSION;
     const cwd = requestedCwd ?? process.cwd();
     const workspace = new WorkspaceContext(cwd);
     const configuredRoot = runtimeEnvironment.CLAUDE_CONFIG_DIR || undefined;
@@ -4436,8 +4437,14 @@ function isDirectExecution(moduleUrl, argvPath) {
 if (isDirectExecution(import.meta.url, process.argv[1])) {
     const controller = new AbortController();
     const cancel = () => controller.abort();
-    process.once('SIGINT', cancel);
-    process.exitCode = await run(process.argv.slice(2), consoleIO, defaultDependencies, controller.signal);
-    process.removeListener('SIGINT', cancel);
+    process.on('SIGINT', cancel);
+    process.on('SIGTERM', cancel);
+    try {
+        process.exitCode = await run(process.argv.slice(2), consoleIO, defaultDependencies, controller.signal);
+    }
+    finally {
+        process.removeListener('SIGINT', cancel);
+        process.removeListener('SIGTERM', cancel);
+    }
 }
 //# sourceMappingURL=cli.js.map

package/dist/compatibility/claude/fork.js

@@ -48,6 +48,7 @@ function validateNativeHistory(entries) {
     }
     const childParentUuids = new Set();
     const externalParentUuids = new Set();
+    let externalParentReferenceCount = 0;
     const completedToolCalls = new Set();
     let ordinaryRootCount = 0;
     let compactBoundary;
@@ -96,6 +97,7 @@ function validateNativeHistory(entries) {
                 }
                 else {
                     externalParentUuids.add(entry.parentUuid);
+                    externalParentReferenceCount += 1;
                 }
             }
         }
@@ -120,7 +122,15 @@ function validateNativeHistory(entries) {
     if (compactBoundary) {
         throw new Error('Claude compact boundary has no adjacent summary');
     }
-    if (externalParentUuids.size > 0 || ordinaryRootCount > 1) {
+    const omittedSeedUserParent = externalParentUuids.size === 1 ? [...externalParentUuids][0] : undefined;
+    const firstEntry = entries[0];
+    const isOmittedSeedUserChain = externalParentUuids.size === 1 &&
+        ordinaryRootCount === 0 &&
+        externalParentReferenceCount === 1 &&
+        firstEntry?.type === 'assistant' &&
+        firstEntry?.parentUuid === omittedSeedUserParent;
+    if ((externalParentUuids.size > 0 && !isOmittedSeedUserChain) ||
+        ordinaryRootCount > 1) {
         throw new Error('Claude fork source has a dangling parentUuid');
     }
     const states = new Map();

package/dist/compatibility/claude/schema.d.ts

@@ -11,6 +11,7 @@ export interface ClaudeSchemaAdapter {
     serializeForSidechainAppend(entry: ClaudeTranscriptEntry): string;
     serializeForFork(entry: ClaudeTranscriptEntry): string;
 }
+export declare const VERIFIED_CLAUDE_SCHEMA_VERSION = "2.1.208";
 export declare function isClaudeForkableEntryType(type: string): boolean;
 export declare function copyClaudeEntryWithSessionId(entry: ClaudeTranscriptEntry, sessionId: string): ClaudeTranscriptEntry;
 export declare function selectClaudeSchemaAdapter(version: string): ClaudeSchemaAdapter;

package/dist/compatibility/claude/schema.js

@@ -1,5 +1,5 @@
 import { isAgentColorValue } from './agent-color.js';
-const SUPPORTED_VERSION = '2.1.208';
+export const VERIFIED_CLAUDE_SCHEMA_VERSION = '2.1.208';
 const APPENDABLE_ENTRY_TYPES = new Set([
     'agent-color',
     'agent-name',
@@ -69,6 +69,7 @@ const FORKABLE_ATTACHMENT_TYPES = new Set([
     'read_truncation_notice',
     'skill_listing',
     'task_reminder',
+    'total_tokens_reminder',
 ]);
 const RAW_CLAUDE_ENTRY = Symbol('raw-claude-entry');
 function parseEntry(line) {
@@ -775,8 +776,8 @@ function validateAppendableEntry(entry) {
             throw new Error(`Claude transcript entry is missing ${field}`);
         }
     }
-    if (entry.version !== SUPPORTED_VERSION) {
-        throw new Error(`Claude transcript append must target Claude Code ${SUPPORTED_VERSION}`);
+    if (entry.version !== VERIFIED_CLAUDE_SCHEMA_VERSION) {
+        throw new Error(`Claude transcript append must target Claude Code ${VERIFIED_CLAUDE_SCHEMA_VERSION}`);
     }
     if (!('parentUuid' in entry) ||
         (entry.parentUuid !== null && !isNonEmptyString(entry.parentUuid))) {
@@ -836,8 +837,8 @@ function validateSidechainEntry(entry) {
             throw new Error(`Claude sidechain entry is missing ${field}`);
         }
     }
-    if (entry.version !== SUPPORTED_VERSION) {
-        throw new Error(`Claude sidechain append must target Claude Code ${SUPPORTED_VERSION}`);
+    if (entry.version !== VERIFIED_CLAUDE_SCHEMA_VERSION) {
+        throw new Error(`Claude sidechain append must target Claude Code ${VERIFIED_CLAUDE_SCHEMA_VERSION}`);
     }
     if (!('parentUuid' in entry) ||
         (entry.parentUuid !== null && !isNonEmptyString(entry.parentUuid))) {
@@ -925,9 +926,11 @@ function validateForkableEntry(entry) {
             throw new Error(`Claude transcript entry is missing ${field}`);
         }
     }
-    if (entry.version !== SUPPORTED_VERSION) {
-        throw new Error(`Claude transcript fork must target Claude Code ${SUPPORTED_VERSION}`);
-    }
+    // A native fork is a lossless copy that retains the source producer's
+    // version as append-only provenance and changes only fork-specific
+    // session-id fields. The strict verified-writer version gate remains on
+    // serializeForAppend and serializeForSidechainAppend; the loop above
+    // already requires a nonempty producer version here.
     if (!('parentUuid' in entry) ||
         (entry.parentUuid !== null && !isNonEmptyString(entry.parentUuid))) {
         throw new Error('Claude transcript entry has invalid parentUuid');
@@ -969,7 +972,7 @@ function validateForkableEntry(entry) {
         validateForkAssistantMessage(entry.message);
 }
 class ClaudeCode21208Adapter {
-    version = SUPPORTED_VERSION;
+    version = VERIFIED_CLAUDE_SCHEMA_VERSION;
     writeMode = 'read-write';
     parse(line) {
         return parseEntry(line);
@@ -1019,7 +1022,7 @@ class ReadOnlyClaudeAdapter {
     }
 }
 export function selectClaudeSchemaAdapter(version) {
-    if (version === SUPPORTED_VERSION) {
+    if (version === VERIFIED_CLAUDE_SCHEMA_VERSION) {
         return new ClaudeCode21208Adapter();
     }
     return new ReadOnlyClaudeAdapter(version);

package/dist/plugins/claude-plugin-runtime.js

@@ -975,6 +975,87 @@ async function writeScaffoldComponent(path, content, preserveExisting) {
         throw error;
     }
 }
+function nativeSkillTemplate(name) {
+    return `---
+name: ${name}
+description: TODO — describe WHEN Claude should use this. Include trigger phrases users
+  might say ("do X", "set up Y", "review Z"). Be specific; this string is what Claude
+  matches the user's request against.
+---
+
+# ${name}
+
+TODO: what this skill does, and the steps Claude should take.
+`;
+}
+function nativeChannelServerTemplate(name) {
+    return `#!/usr/bin/env bun
+/**
+ * ${name} channel server — stdio MCP server implementing the channel contract.
+ * See https://docs.claude.com/en/docs/claude-code/channels-reference.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+
+const mcp = new Server(
+  { name: '${name}', version: '0.1.0' },
+  {
+    capabilities: {
+      tools: {},
+      // Required: presence of this key registers the channel notification
+      // listener on Claude's side.
+      experimental: { 'claude/channel': {} },
+    },
+    instructions:
+      "Events from ${name} arrive as <channel source=\\"${name}\\" ...>. Anything " +
+      "you want the sender to see must go through the reply tool — your " +
+      "transcript output never reaches the channel.",
+  },
+)
+
+mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'reply',
+      description: 'Send a message back to the ${name} channel.',
+      inputSchema: {
+        type: 'object',
+        properties: { text: { type: 'string' } },
+        required: ['text'],
+      },
+    },
+  ],
+}))
+
+mcp.setRequestHandler(CallToolRequestSchema, async req => {
+  const args = (req.params.arguments ?? {}) as Record<string, unknown>
+  if (req.params.name === 'reply') {
+    // TODO: deliver args.text to the external service.
+    return { content: [{ type: 'text', text: 'sent' }] }
+  }
+  return { content: [{ type: 'text', text: 'unknown tool' }], isError: true }
+})
+
+// TODO: when the external service has an inbound event, push it to Claude:
+//
+//   await mcp.notification({
+//     method: 'notifications/claude/channel',
+//     params: {
+//       content: 'the event body',
+//       meta: { chat_id: '...', sender: '...' },
+//     },
+//   })
+//
+// Each meta key becomes an attribute on the <channel> tag. Keys must be
+// identifiers (letters/digits/underscores) — others are silently dropped.
+
+await mcp.connect(new StdioServerTransport())
+`;
+}
 export async function initClaudePlugin(path, name = basename(resolve(path)), options = {}) {
     if (!PLUGIN_NAME.test(name))
         throw new Error(`Plugin name must match ${PLUGIN_NAME}`);
@@ -1029,42 +1110,68 @@ export async function initClaudePlugin(path, name = basename(resolve(path)), opt
         };
     await writeScaffoldFile(join(manifestDirectory, 'plugin.json'), `${JSON.stringify(manifest, null, 2)}\n`, options.force === true);
     if (nativeLayout) {
-        await writeScaffoldComponent(join(root, 'SKILL.md'), `---\nname: ${name}\ndescription: TODO — describe when Claude should use this plugin.\n---\n\n# ${name}\n\nTODO: what this plugin does.\n`, options.force === true);
+        await writeScaffoldComponent(join(root, 'SKILL.md'), nativeSkillTemplate(name), options.force === true);
     }
     else {
         await writeScaffoldComponent(join(root, 'commands', 'hello.md'), '# Hello\n\nDescribe the current workspace.\n', options.force === true);
     }
     if (components.has('skills')) {
-        await writeScaffoldComponent(join(root, 'skills', 'example', 'SKILL.md'), '---\nname: example\ndescription: Example plugin skill\n---\n\nUse this skill to inspect the workspace.\n', options.force === true);
+        await writeScaffoldComponent(join(root, 'skills', 'example', 'SKILL.md'), nativeSkillTemplate('example'), options.force === true);
     }
     if (components.has('agents')) {
-        await writeScaffoldComponent(join(root, 'agents', nativeLayout ? 'example.md' : 'reviewer.md'), '---\nname: example\ndescription: Review changes\n---\n\nReview the current changes.\n', options.force === true);
+        await writeScaffoldComponent(join(root, 'agents', nativeLayout ? 'example.md' : 'reviewer.md'), nativeLayout
+            ? '---\nname: example\ndescription: TODO — when should Claude delegate to this subagent?\ntools:\n  - Read\n  - Grep\n---\n\nTODO: system prompt for the subagent.\n'
+            : '---\nname: example\ndescription: Review changes\n---\n\nReview the current changes.\n', options.force === true);
     }
     if (components.has('hooks')) {
-        await writeScaffoldComponent(join(root, 'hooks', 'hooks.json'), '{\n  "hooks": {\n    "SessionStart": []\n  }\n}\n', options.force === true);
+        if (nativeLayout) {
+            await writeScaffoldComponent(join(root, 'hooks-handlers', 'on-session-start.ts'), '#!/usr/bin/env bun\n// SessionStart hook handler. Reads the event from stdin, writes a JSON result\n// to stdout. Swap "bun" for "node" or "python3" in hooks/hooks.json if your\n// users\' environment lacks bun.\nconst input = await new Response(Bun.stdin.stream()).text()\nconst event = JSON.parse(input)\nprocess.stdout.write(JSON.stringify({}))\n', options.force === true);
+        }
+        await writeScaffoldComponent(join(root, 'hooks', 'hooks.json'), nativeLayout
+            ? '{\n  "hooks": {\n    "SessionStart": [\n      {\n        "hooks": [\n          {\n            "type": "command",\n            "command": "bun ${CLAUDE_PLUGIN_ROOT}/hooks-handlers/on-session-start.ts"\n          }\n        ]\n      }\n    ]\n  }\n}\n'
+            : '{\n  "hooks": {\n    "SessionStart": []\n  }\n}\n', options.force === true);
     }
     if (components.has('mcp') || components.has('channel')) {
-        await writeScaffoldComponent(join(root, '.mcp.json'), `${JSON.stringify({
-            mcpServers: {
-                [components.has('channel') ? name : 'example']: {
+        const mcpServers = components.has('channel')
+            ? {
+                [name]: {
+                    command: 'bun',
+                    args: [
+                        'run',
+                        '--cwd',
+                        '${CLAUDE_PLUGIN_ROOT}',
+                        '--shell=bun',
+                        '--silent',
+                        'start',
+                    ],
+                },
+            }
+            : {
+                'example-remote': {
+                    type: 'http',
+                    url: 'https://example.com/mcp',
+                },
+                'example-local': {
                     command: 'npx',
                     args: ['<your-mcp-server-package>'],
                 },
-            },
-        }, null, 2)}\n`, options.force === true);
+            };
+        await writeScaffoldComponent(join(root, '.mcp.json'), `${JSON.stringify({ mcpServers }, null, 2)}\n`, options.force === true);
     }
     if (components.has('lsp')) {
-        await writeScaffoldComponent(join(root, '.lsp.json'), '{\n  "example": {\n    "command": "example-language-server",\n    "args": ["--stdio"]\n  }\n}\n', options.force === true);
+        await writeScaffoldComponent(join(root, '.lsp.json'), '{\n  "example": {\n    "command": "example-language-server",\n    "args": [\n      "--stdio"\n    ],\n    "extensionToLanguage": {\n      ".example": "example"\n    }\n  }\n}\n', options.force === true);
     }
     if (components.has('output-style')) {
-        await writeScaffoldComponent(join(root, 'output-styles', `${name}.md`), `---\nname: ${name}\ndescription: TODO — output style description\nforce-for-plugin: true\n---\n\nTODO: style instructions.\n`, options.force === true);
+        await writeScaffoldComponent(join(root, 'output-styles', `${name}.md`), `---\nname: ${name}\ndescription: TODO — one line shown in the Output style picker in /config\nforce-for-plugin: true\nkeep-coding-instructions: true\n---\n\nTODO: the style prompt. This is appended to Claude's system prompt while the\nstyle is active. With force-for-plugin: true, the style applies automatically\nwhen this plugin is enabled.\n`, options.force === true);
     }
     if (components.has('channel')) {
-        await writeScaffoldComponent(join(root, 'server.ts'), '// TODO: implement channel server.\n', options.force === true);
+        await writeScaffoldComponent(join(root, 'server.ts'), nativeChannelServerTemplate(name), options.force === true);
         await writeScaffoldComponent(join(root, 'package.json'), `${JSON.stringify({
             name: `claude-channel-${name}`,
             version: '0.1.0',
             type: 'module',
+            scripts: { start: 'bun install --no-summary && bun server.ts' },
+            dependencies: { '@modelcontextprotocol/sdk': '^1.0.0' },
         }, null, 2)}\n`, options.force === true);
     }
     return validateClaudePlugin(root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",
@@ -62,6 +62,11 @@
     "test:mcp-resource-compat": "npm run build && node scripts/verify-mcp-resource-compatibility.mjs",
     "test:notebook-compat": "npm run build && node scripts/verify-notebook-compatibility.mjs",
     "test:context-compat": "npm run build && node scripts/verify-context-runtime.mjs",
+    "test:cross-version-session-compat": "npm run build && node scripts/verify-cross-version-session-compatibility.mjs",
+    "test:cross-version-resume-at-compat": "npm run build && node scripts/verify-cross-version-resume-at-compatibility.mjs",
+    "test:cross-version-fork-compat": "npm run build && node scripts/verify-cross-version-fork-compatibility.mjs",
+    "test:cross-version-sidechain-compat": "npm run build && node scripts/verify-cross-version-sidechain-compatibility.mjs",
+    "test:cross-version-compaction-compat": "npm run build && node scripts/verify-cross-version-compaction-compatibility.mjs",
     "test:dynamic-system-compat": "npm run build && node scripts/verify-dynamic-system-prompt.mjs",
     "test:permission-compat": "npm run build && node scripts/verify-claude-permissions.mjs",
     "test:permission-prompt-compat": "npm run build && node scripts/verify-permission-prompt-tool.mjs",