@kodax-ai/kodax 0.7.71 → 0.7.72

package/dist/types-chunks/{utils.d-Cb6vdvFM.d.ts → utils.d-gmn3c5U4.d.ts}

@@ -1,9 +1,9 @@
 import { k as KodaXMessage, F as KodaXReasoningMode, d as KodaXCustomProviderConfig, p as KodaXProviderCapabilityProfile } from './types.d-Cqaw71Ax.js';
-import { I as KodaXContextTokenSnapshot, ae as KodaXSkillDynamicContextPolicy, r as KodaXAgentMode, a1 as KodaXRepoIntelligenceMode, Y as KodaXOptions, af as KodaXSkillInvocationContext } from './bash-prefix-extractor.d-YoiZl5yt.js';
-import { bm as KodaXSessionUiHistoryItem, bb as KodaXSessionLineage, b2 as KodaXSessionArtifactLedgerEntry, aO as KodaXExtensionSessionState, aN as KodaXExtensionSessionRecord, bi as KodaXSessionRuntimeInfo, dA as WorkflowProcessSource } from './types.d-CRCaLt_s.js';
-import { A as AgentsFile, f as AutoModeStats, l as KodaXMcpServersConfig } from './guardrail.d-DdeDWnVu.js';
+import { M as KodaXContextTokenSnapshot, ah as KodaXSkillDynamicContextPolicy, t as KodaXAgentMode, a4 as KodaXRepoIntelligenceMode, $ as KodaXOptions, ai as KodaXSkillInvocationContext } from './bash-prefix-extractor.d-CHJO5y94.js';
+import { bW as KodaXSessionUiHistoryItem, bL as KodaXSessionLineage, bC as KodaXSessionArtifactLedgerEntry, bm as KodaXExtensionSessionState, bl as KodaXExtensionSessionRecord, bS as KodaXSessionRuntimeInfo, ea as WorkflowProcessSource } from './types.d-DH1mvdcl.js';
+import { d as AgentsFile, j as AutoModeStats, p as KodaXMcpServersConfig } from './guardrail.d-auV61_h5.js';
 import * as readline from 'readline';
-import { f as PermissionMode } from './public-api.d-BvCp5VkW.js';
+import { R as PermissionMode, L as LearningBinding, E as LearningSurfaceSnapshot } from './public-api.d--IDNJsu1.js';
 import { SpawnSyncReturns } from 'child_process';
 
 /**
@@ -227,6 +227,9 @@ interface CommandCallbacks {
     rewindSession?: (selector?: string) => Promise<SessionRewindStatus>;
     getCostReport?: () => string | null;
     getRuntimeStatus?: () => Promise<RuntimeSurfaceStatus | undefined>;
+    learning?: LearningBinding;
+    getLearningSummary?: () => Promise<LearningSurfaceSnapshot>;
+    openLearningCenter?: (nameOrSlug?: string) => Promise<void>;
     /**
      * FEATURE_092 phase 2b.8: read-only stats accessor for the auto-mode
      * classifier guardrail. Returns undefined when the guardrail hasn't been
@@ -258,14 +261,8 @@ interface CommandInvocationRequest extends CommandExecutionMetadata {
     displayName: string;
     path?: string;
     skillInvocation?: KodaXSkillInvocationContext;
-    /**
-     * FEATURE_246: per-turn agent-mode elevation for this invocation only.
-     * The `/workflow` command in AMA sets this to `'amaw'` so its authoring turn
-     * gets `run_workflow` (scout-then-author) — matching AMAW's capability without
-     * making plain AMA self-activate workflows from natural language. The session
-     * mode is unchanged; only this one turn runs elevated.
-     */
-    agentModeOverride?: KodaXAgentMode;
+    /** Trusted host marker set only by an explicit Workflow command. */
+    workflowIntent?: 'explicit';
 }
 interface CommandWorkflowInvocationRequest {
     request: string;

package/docs/SDK_EMBEDDER_GUIDE.md

@@ -2169,17 +2169,30 @@ For streaming follow-ups, use `enqueueWithArtifacts()` instead of the raw
 message queue:
 
 ```ts
-enqueueWithArtifacts({
-  provider: selectedProvider,
-  model: selectedModel,
-  content: followupText,
-  inputArtifacts: [artifact],
-});
-```
-
-The helper validates first and then stores `inputArtifacts` on the queued prompt.
-Queued image follow-ups are rebuilt as multimodal content blocks on the next
-runner turn. Unsupported file/video attachments are rejected before enqueueing.
+enqueueWithArtifacts({
+  provider: selectedProvider,
+  model: selectedModel,
+  sessionId: activeSessionId,
+  content: followupText,
+  inputArtifacts: [artifact],
+});
+```
+
+The helper validates first and then stores `inputArtifacts` on the queued prompt.
+Queued image follow-ups are rebuilt as multimodal content blocks on the next
+runner turn. Unsupported file/video attachments are rejected before enqueueing.
+Pass `sessionId` whenever the host can run more than one session concurrently;
+it targets that Actor session's root queue without exposing Actor paths. For
+backward compatibility, omitting both `sessionId` and `agentId` still binds to
+the sole active Actor root, or uses the legacy unscoped SA queue when no Actor
+run is active. If multiple Actor roots are active, the helper rejects the
+ambiguous call instead of risking cross-session delivery. Low-level child-Actor
+producers may continue to pass an explicit `agentId`.
+
+`enqueueWithArtifacts()` is an in-process queue helper for direct/inline runs.
+Runtime Worker and daemon clients must use `runtime.runs.submitInput(...)` (with
+the same `sessionId`, `afterRunId`, and `delivery:'after_turn'`) because a
+process-local MessageQueue cannot cross those transport boundaries.
 
 ### Boundaries
 
@@ -2521,10 +2534,16 @@ For a given profile, one owner wins an atomic lock. Concurrent starters wait for
 the winner and connect once it is ready. Stale state is cleaned only after pid,
 endpoint, token, and runtime identity checks. If ownership cannot be verified,
 KodaX reports the daemon as unhealthy instead of killing an arbitrary process.
-SDK auto-start launches a detached `kodax daemon serve` process; it never treats
-an in-process socket listener as daemon mode. Closing the SDK client detaches
-without stopping that shared process. Use `kodax daemon stop` or the explicit
-runtime shutdown protocol to stop the owner.
+SDK auto-start launches a detached `kodax daemon serve` process; it never treats
+an in-process socket listener as daemon mode. Closing the SDK client detaches
+without stopping that shared process. Use `kodax daemon stop` or the explicit
+runtime shutdown protocol to stop the owner.
+
+CLI and SDK startup retain the exact spawned candidate until health confirms
+that candidate PID. Early exit, timeout, identity mismatch, cancellation, or a
+different owner winning the race reclaims only the unsuccessful candidate
+process tree. Once healthy, the owner detaches normally and is not tied to the
+creating client process.
 
 ### Daemon startup, conflict, and recovery behavior
 
@@ -2548,6 +2567,9 @@ Operational guidance:
 - test harnesses that auto-start a process daemon must send authenticated
   `runtime.shutdown` (or run `kodax daemon stop --home <dir> --profile <name>`)
   before deleting their temporary home; `runtime.close()` only detaches;
+- KodaX's own Vitest harness also supplies an internal worker-PID marker so a
+  forcibly terminated worker cannot strand its test daemon; this is a test-only
+  fallback, not a public SDK option or a production idle-shutdown policy;
 - query `kodax daemon status --json` before deciding to restart;
 - inspect `kodax daemon logs --lines 100` when startup times out;
 - custom endpoints and injected transports are attach-only unless the caller
@@ -2599,11 +2621,14 @@ runtime close.
 ```ts
 const session = await runtime.sessions.create({ title: 'Shared session' });
 
-const sub = runtime.events.subscribe({ sessionId: session.id }, (event) => {
-  if (event.type === 'assistant.delta') {
-    // Render streaming text in the host UI.
-  }
-});
+const sub = runtime.events.subscribe({ sessionId: session.id }, (event) => {
+  if (event.type === 'assistant.delta') {
+    // Render streaming text in the host UI.
+  }
+});
+// Daemon subscriptions establish a remote handshake. Await this before
+// starting work whose first event must not be missed; local subscriptions omit it.
+await sub.ready;
 
 const artifact = await runtime.artifacts.create({
   kind: 'image',
@@ -2661,7 +2686,7 @@ Space-style client can subscribe to permission events and answer a request
 created by a REPL-style client.
 
 ```ts
-const sub = runtime.events.subscribe({ type: 'permission.requested' }, (event) => {
+const sub = runtime.events.subscribe({ type: 'permission.requested' }, (event) => {
   const payload = event.payload;
   if (!payload || typeof payload !== 'object' || typeof payload.id !== 'string') {
     return;
@@ -2670,11 +2695,14 @@ const sub = runtime.events.subscribe({ type: 'permission.requested' }, (event) =
     payload.id,
     { type: 'allow_once' },
     { runId: payload.runId },
-  );
-});
-```
-
-Only the first valid response wins. Wrong-run or stale responses are rejected.
+  );
+});
+await sub.ready;
+```
+
+Await `ready` before another client starts work that may request permission;
+this creates an explicit cross-connection ordering boundary. Only the first
+valid response wins. Wrong-run or stale responses are rejected.
 Abort, runtime close, daemon stop, and timeout reject unresolved permission
 requests so tool approval promises do not hang forever.
 
@@ -3693,6 +3721,7 @@ const runtime = await connectKodaXRuntime({
     sharedSessionSettings: 1,
     durableRecoveryQueries: 1,
     daemonManagement: 1,
+    runtimeAutoModeGuardrail: 1,
   },
 });
 ```
@@ -3704,6 +3733,18 @@ Coder. FEATURE_269 does not advertise `interruptInput`, so an interrupt-only
 product must require `{ interruptInput: 1 }` and fail connection. The supported
 fallback is `delivery: 'after_turn'` only when that is the user's intent.
 
+The final v0.7.72 SDK requires `runtimeAutoModeGuardrail:1` automatically for
+`autoStart: true`, even when the caller omits it from `requirements`. If the healthy
+profile daemon is older, the SDK first requires `daemonManagement:1`, takes a
+revision/owner-policy fenced preflight, and replaces it only when no active or
+queued run, Workflow, Agent turn, pending permission/user input, or other
+logical client exists. A busy or still-older daemon is never stopped: the
+connection rejects with `RuntimeDaemonCapabilityUpgradeError`, whose
+`recoverable` and `restartRequired` fields are `true` and whose optional
+`preflight` explains the blockers. Attach-only connections never mutate daemon
+ownership and must request `runtimeAutoModeGuardrail:1` explicitly when they
+depend on this contract.
+
 The `coderFeatureMatrix` capability reports daemon availability for managed
 runs, transcript/session operations, Todo projection, managed tasks, Workflow,
 MCP, Reference External Agent, Memory, and Runtime artifacts. Reference
@@ -4091,6 +4132,110 @@ tool arguments.
 
 ---
 
+## 24. Runtime-owned Auto Mode and plan-approval bridges (v0.7.72)
+
+Auto Mode is a Runtime session contract, including in shared-daemon mode. Do
+not implement a second classifier or decide permissions from a client-side
+`beforeToolExecute` hook before the Runtime has classified the call.
+
+### Configure the session, not an individual UI callback
+
+```ts
+await runtime.sessions.updateSettings(session.id, {
+  permissionMode: 'auto',
+  autoModeEngine: 'llm',
+  autoModeClassifierModel: 'zhipu:glm-5.2', // optional; otherwise follow the run model
+  autoModeTimeoutMs: 20_000,                // positive safe integer, optional
+  executionCwd: projectDirectory,
+});
+```
+
+`autoModeClassifierModel` and `autoModeTimeoutMs` are durable session settings
+in inline, Worker, and daemon forms. A `null` patch removes either optional
+override; a zero, negative, fractional, or unsafe timeout is rejected. Daemon
+capability discovery advertises both fields in `sharedSessionSettings.keys`.
+
+The Runtime owns one serialized permission-settings stream and one shared
+engine/denial/breaker state per Session. It reuses bounded context-specific
+guardrails across turns while provider/model, repository boundary, execution
+directory, classifier model, and timeout remain the same. Updating one of
+those inputs selects a new context guardrail by design without copying stale
+state from a queued turn. Active runs, queued runs, explicit settings updates,
+and automatic LLM-to-rules fallback merge through the same Session mutation
+queue; fallback is persisted before a later classification reads the engine.
+
+### What an embedder should expect
+
+The Runtime's execution order is fixed:
+
+```text
+Runtime Auto Mode guardrail -> host permission bridge only for escalate -> tool execution
+```
+
+Consequently, an LLM/rules `allow` does not create a pending permission request
+just because a host installed a static approval hook. `block` does not become a
+spurious approval prompt. A real `escalate` uses the existing shared
+`runtime.permissions` flow, so another authorized client may render and answer
+it. Hosts should subscribe to permission events to display such a request, but
+must not treat a missing request as an error for a safe tool call.
+
+The permission event's `inputPreview` is a display-safe diagnostic projection:
+it is bounded, credential-redacted, valid JSON, and includes the effective
+execution directory. Use the Runtime owner’s typed tool input for execution;
+do not reconstruct or authorize a tool from the preview. `gitRoot` remains the
+session repository safety boundary, whereas relative operands resolve from the
+validated `executionCwd`. In particular, quoted Python/JavaScript/regexp source
+inside a shell command is not a path operand.
+
+The user-level `.kodax` directory is a credential/configuration boundary, not
+an ordinary project path. Direct shell mutations, output redirects, and
+recognized nested-shell payloads whose target is provably beneath that
+directory are rejected before LLM classification. The check is segment-safe
+and Windows case-insensitive. KodaX deliberately does not scan arbitrary
+quoted language source for path-looking substrings: doing so would turn Python,
+JavaScript, YAML, and regular expressions into false Tier-0 matches. Trusted
+configuration changes should use the KodaX config CLI or SDK configuration API.
+
+### 0.7.x source compatibility
+
+The v0.7.72 public declarations retain the following migration aliases:
+
+| Legacy source | Current source | Contract |
+|---|---|---|
+| `agentMode: 'amaw'` | `'ama'` | accepted as deprecated input and normalized to AMA; no separate AMAW runtime is restored |
+| `SkillSource` | `ResolvedSkillSource` | formal source union remains `project \| user \| plugin \| builtin`; only resolved discovery output adds `learned` |
+| `RuntimeDaemonPreflight.activeAgentTasks` | `activeAgentTurns` | both required fields are returned and reference the same array throughout the 0.7.x line |
+
+### Plan capability is opt-in
+
+`exit_plan_mode` is exposed to a Runtime run only when that run supplies an
+approval bridge. A daemon or headless host that cannot approve a plan should
+leave the bridge absent; KodaX removes the tool from that run's scope.
+
+```ts
+const planned = await runtime.runs.start({
+  sessionId: session.id,
+  prompt: 'Draft a migration plan, then ask for approval.',
+  options: {
+    events: {
+      exitPlanMode: async () => showPlanAndAskUser(),
+    },
+  },
+});
+await planned.result;
+```
+
+The callback belongs in a trusted host process (for Electron, Main rather than
+renderer). It is intentionally not inferred from the presence of a permission
+UI: tool permission and plan approval are different user decisions.
+
+See [ADR-056](ADR.md#adr-056-runtime-owns-auto-mode-permission-decisions-and-host-capability-exposure)
+for the ownership decision, [the v0.7.72 design](features/v0.7.72.md#2026-07-18-runtime-permission-queue-and-resume-closure)
+for the release boundary, and [Known Issue 187](KNOWN_ISSUES.md#187-shared-daemon-auto-permission-ownership-upgrade-fencing-preview-bounds-and-sdk-compatibility-were-incomplete)
+for the final capability-upgrade and compatibility closure.
+
+---
+
 ## See also
 
 - [README.md](../README.md) — end-user CLI quick start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodax-ai/kodax",
-  "version": "0.7.71",
+  "version": "0.7.72",
   "description": "KodaX lightweight coding agent - TypeScript implementation with 15 built-in LLM provider aliases, published as a Node-free single-file CLI and SDK",
   "type": "module",
   "private": false,
@@ -73,13 +73,13 @@
     "build:dts": "node scripts/build-dts.mjs",
     "build:packages": "tsc -b tsconfig.build.json && npm run copy:builtin -w @kodax-ai/agent && npm run copy:provider-caps -w @kodax-ai/llm",
     "build:bundle": "node scripts/build-bundle.mjs",
-    "dev": "node --max-old-space-size=4096 --require ./scripts/production-env.cjs --import tsx src/kodax_cli.ts",
-    "dev:cli": "node --max-old-space-size=4096 --require ./scripts/production-env.cjs --import tsx src/kodax_cli.ts",
+    "dev": "node --max-old-space-size=4096 --require ./scripts/production-env.cjs --import tsx src/kodax_bootstrap.ts",
+    "dev:cli": "node --max-old-space-size=4096 --require ./scripts/production-env.cjs --import tsx src/kodax_bootstrap.ts",
     "dev:mem-diag": "node scripts/mem-diag-launch.cjs",
     "dev:mem-snapshot": "node scripts/mem-diag-launch.cjs 2",
     "probe:reasoning": "tsx scripts/probe-reasoning.ts",
     "probe:max-tokens": "node scripts/probe-max-tokens.mjs",
-    "start": "node --max-old-space-size=4096 --require ./scripts/production-env.cjs dist/kodax_cli.js",
+    "start": "node --max-old-space-size=4096 --require ./scripts/production-env.cjs dist/kodax_bootstrap.js",
     "build:binary": "node scripts/build-binary.mjs",
     "build:binary:all": "node scripts/build-binary.mjs --all",
     "test": "vitest run",

package/scripts/kodax-bin.cjs

@@ -11,7 +11,7 @@
  * development reconciler, leaking ~100 MB/turn of profiling objects.
  *
  * This CJS file runs synchronously first, requires the env preload,
- * then dynamic-imports the compiled ESM entry.
+ * then dynamic-imports the lightweight compiled bootstrap.
  *
  * Opt back into development by setting KODAX_DEV=1.
  */
@@ -19,7 +19,9 @@
 
 require('./production-env.cjs');
 
-import('../dist/kodax_cli.js').catch((err) => {
+import('../dist/kodax_bootstrap.js').then(
+  ({ runKodaXBootstrapAsEntry }) => runKodaXBootstrapAsEntry(),
+).catch((err) => {
   // Surface unexpected errors with a full stack — this path should be rare.
   // eslint-disable-next-line no-console
   console.error(err);

package/scripts/production-env.cjs

@@ -14,3 +14,12 @@
 if (!process.env.NODE_ENV) {
   process.env.NODE_ENV = process.env.KODAX_DEV === '1' ? 'development' : 'production';
 }
+
+// Bootstrap hardening must run before the first application ESM import.
+// ELECTRON_RUN_AS_NODE is a one-shot exec-boundary switch and is never kept.
+delete process.env.ELECTRON_RUN_AS_NODE;
+if (process.env.KODAX_DISABLE_HARDENING !== '1') {
+  delete process.env.LD_PRELOAD;
+  delete process.env.DYLD_INSERT_LIBRARIES;
+  delete process.env.DYLD_LIBRARY_PATH;
+}

package/dist/chunks/agent-X2EWQADL.js

@@ -1,2 +0,0 @@
-// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{Ga as i,K as c,L as d,M as e,Ma as j,N as f,ma as g,na as h}from"./chunk-T7LYK53M.js";import"./chunk-64NQBOSN.js";import"./chunk-44QXPEEE.js";import"./chunk-PVUXONQB.js";import"./chunk-ZJIMT5I3.js";import{vb as a,wb as b}from"./chunk-Y5XKAN7C.js";import"./chunk-52JSZ77P.js";import"./chunk-VRSVNU2Y.js";import"./chunk-23X6REO4.js";import"./chunk-ONUPGMER.js";export{d as bucketProviderPayloadSize,g as buildAutoRepoIntelligenceContext,e as checkPromiseSignal,b as cleanupIncompleteToolCalls,h as describeTransientProviderRetry,f as emitResilienceDebug,c as estimateProviderPayloadBytes,j as runKodaX,i as saveSessionSnapshot,a as validateAndFixToolHistory};

package/dist/chunks/argument-completer-BLNXDO2F.js

@@ -1,2 +0,0 @@
-// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{Ba as a,Ca as b}from"./chunk-F7KGYHJ3.js";import"./chunk-GVTM4Z6O.js";import"./chunk-SX2WFHIS.js";import"./chunk-A574DBTV.js";import"./chunk-A2TFSV5M.js";import"./chunk-PHH4TRGF.js";import"./chunk-T7LYK53M.js";import"./chunk-64NQBOSN.js";import"./chunk-44QXPEEE.js";import"./chunk-PVUXONQB.js";import"./chunk-ZJIMT5I3.js";import"./chunk-Y5XKAN7C.js";import"./chunk-52JSZ77P.js";import"./chunk-VRSVNU2Y.js";import"./chunk-23X6REO4.js";import"./chunk-ONUPGMER.js";export{a as ArgumentCompleter,b as createArgumentCompleter};