@kodax-ai/kodax 0.7.77 → 0.7.78

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/CHANGELOG.md +176 -4
  2. package/README.md +200 -64
  3. package/README_CN.md +153 -49
  4. package/config-templates/config.example.jsonc +114 -32
  5. package/dist/chunks/agent-ASP4MS3X.js +2 -0
  6. package/dist/chunks/argument-completer-JYQ7FX3W.js +2 -0
  7. package/dist/chunks/{chunk-XSA37BVM.js → chunk-2CFHBKRE.js} +1 -1
  8. package/dist/chunks/chunk-35PPHOQ2.js +292 -0
  9. package/dist/chunks/chunk-43QNNDHR.js +29 -0
  10. package/dist/chunks/chunk-5BNQXXGY.js +1 -0
  11. package/dist/chunks/chunk-5GO6FH7L.js +458 -0
  12. package/dist/chunks/{chunk-FSXI4MAV.js → chunk-5NDCSFOP.js} +14 -14
  13. package/dist/chunks/{chunk-3DD4QEBH.js → chunk-6FOJVETH.js} +10 -10
  14. package/dist/chunks/chunk-6XM4B6K2.js +48 -0
  15. package/dist/chunks/chunk-6YZUE6NC.js +240 -0
  16. package/dist/chunks/{chunk-HORNWBYR.js → chunk-7OEBJGHK.js} +1 -1
  17. package/dist/chunks/{chunk-OAMKECRG.js → chunk-KQLQYHWU.js} +205 -200
  18. package/dist/chunks/{chunk-IQT4RPCE.js → chunk-NXO6GWSY.js} +2 -2
  19. package/dist/chunks/chunk-T2XZTLYE.js +316 -0
  20. package/dist/chunks/chunk-TQDBTTIM.js +348 -0
  21. package/dist/chunks/{chunk-FNW2XUL5.js → chunk-UID7BLAB.js} +1 -1
  22. package/dist/chunks/chunk-VAT2QYXM.js +765 -0
  23. package/dist/chunks/chunk-YAZQTC2L.js +5 -0
  24. package/dist/chunks/chunk-YVRYHC4C.js +655 -0
  25. package/dist/chunks/{chunk-EH7AOMJ7.js → chunk-Z3KFRTSB.js} +1 -1
  26. package/dist/chunks/compaction-config-BQSSIWK5.js +2 -0
  27. package/dist/chunks/{construction-bootstrap-RPRL3L7R.js → construction-bootstrap-VQLQGWPY.js} +1 -1
  28. package/dist/chunks/{dist-FDSOIR35.js → dist-BFT5YIGU.js} +1 -1
  29. package/dist/chunks/dist-PCFE24YP.js +2 -0
  30. package/dist/chunks/host-UTFXCYYM.js +2 -0
  31. package/dist/chunks/run-manager-PJU3WIFJ.js +2 -0
  32. package/dist/chunks/utils-SID4HW2Q.js +2 -0
  33. package/dist/index.d.ts +18 -17
  34. package/dist/index.js +6 -6
  35. package/dist/kodax_cli.js +1751 -1352
  36. package/dist/kodax_resume.js +17 -17
  37. package/dist/runtime-worker.js +1680 -1299
  38. package/dist/sandbox-workspace-session.js +563 -0
  39. package/dist/sdk-a2a.d.ts +16 -16
  40. package/dist/sdk-a2a.js +8 -8
  41. package/dist/sdk-agent.d.ts +275 -60
  42. package/dist/sdk-agent.js +1 -1
  43. package/dist/sdk-coding.d.ts +33 -165
  44. package/dist/sdk-coding.js +1 -1
  45. package/dist/sdk-experimental-memory.d.ts +2 -2
  46. package/dist/sdk-experimental-memory.js +1 -1
  47. package/dist/sdk-llm.d.ts +2 -1
  48. package/dist/sdk-llm.js +1 -1
  49. package/dist/sdk-mcp.js +1 -1
  50. package/dist/sdk-media.js +1 -1
  51. package/dist/sdk-repl.d.ts +67 -25
  52. package/dist/sdk-repl.js +2 -2
  53. package/dist/sdk-runtime.d.ts +194 -147
  54. package/dist/sdk-runtime.js +1 -1
  55. package/dist/sdk-sandbox.d.ts +93 -0
  56. package/dist/sdk-sandbox.js +2 -0
  57. package/dist/sdk-session.d.ts +6 -7
  58. package/dist/sdk-session.js +1 -1
  59. package/dist/sdk-skills.d.ts +2 -2
  60. package/dist/sdk-skills.js +1 -1
  61. package/dist/semantic-worker.js +15 -15
  62. package/dist/types-chunks/{bash-prefix-extractor.d-pZdu6qt7.d.ts → bash-prefix-extractor.d-uAe2Oqda.d.ts} +126 -8
  63. package/dist/types-chunks/{capsule.d-CxCm1KZz.d.ts → capsule.d-BlSv9l3V.d.ts} +1 -1
  64. package/dist/types-chunks/{guardrail.d-CJx9RRd3.d.ts → guardrail.d-BRE_ErEj.d.ts} +1 -1
  65. package/dist/types-chunks/{guardrail.d-B0PwAZVR.d.ts → guardrail.d-CXDYRgZ3.d.ts} +200 -34
  66. package/dist/types-chunks/{history-retrieval.d-B__aEN62.d.ts → history-retrieval.d-DtCy7x64.d.ts} +1 -1
  67. package/dist/types-chunks/{integration-config.d-ojG4swOP.d.ts → integration-config.d-BNowXE8k.d.ts} +23 -8
  68. package/dist/types-chunks/{public-api.d--fF88JrC.d.ts → public-api.d-B3AohsxN.d.ts} +36 -7
  69. package/dist/types-chunks/{commands.d-BccESAMV.d.ts → repl.d-Ie_ZXb_U.d.ts} +89 -78
  70. package/dist/types-chunks/{side-query.d-5JvXhuOZ.d.ts → resolver.d-iAQ9ocLB.d.ts} +3 -66
  71. package/dist/types-chunks/{run-manager.d-B47hIqnI.d.ts → run-manager.d-D1twIhF9.d.ts} +1 -1
  72. package/dist/types-chunks/{sdk-session-CLWf8Adb.d.ts → sdk-session-DB9KksIx.d.ts} +2 -2
  73. package/dist/types-chunks/side-query.d-DTuLPcC5.d.ts +77 -0
  74. package/dist/types-chunks/{types-LanCEDj8.d.ts → types-D3g6XUQr.d.ts} +41 -2
  75. package/dist/types-chunks/{types.d-RdWRfUEs.d.ts → types.d-BA-Jwpfs.d.ts} +459 -7
  76. package/dist/types-chunks/{types.d-CODuyyqy.d.ts → types.d-BH0ZkTGf.d.ts} +1 -1
  77. package/dist/types-chunks/{types.d-DCQVBqVn.d.ts → types.d-BbtGlKZu.d.ts} +25 -3
  78. package/dist/types-chunks/{types.d-DCsKM8aT.d.ts → types.d-DVDTIfB_.d.ts} +2 -2
  79. package/dist/types-chunks/{utils.d-CDduqbFw.d.ts → utils.d-CVp6bFl9.d.ts} +22 -6
  80. package/docs/SDK_EMBEDDER_GUIDE.md +399 -55
  81. package/package.json +8 -1
  82. package/dist/chunks/agent-NGSWFE73.js +0 -2
  83. package/dist/chunks/argument-completer-WGGZPEEO.js +0 -2
  84. package/dist/chunks/chunk-27QLRH3D.js +0 -5
  85. package/dist/chunks/chunk-2MQPVY6P.js +0 -770
  86. package/dist/chunks/chunk-6WAPVAGQ.js +0 -74
  87. package/dist/chunks/chunk-AOENDSVN.js +0 -448
  88. package/dist/chunks/chunk-HV2GMZUZ.js +0 -343
  89. package/dist/chunks/chunk-JS2BHGJP.js +0 -158
  90. package/dist/chunks/chunk-ON2WG2LG.js +0 -622
  91. package/dist/chunks/chunk-RUGAAHTF.js +0 -321
  92. package/dist/chunks/chunk-TGCG7U2W.js +0 -37
  93. package/dist/chunks/compaction-config-BE7VYWH6.js +0 -2
  94. package/dist/chunks/dist-ZZBNVTKU.js +0 -2
  95. package/dist/chunks/host-QAKQVC4A.js +0 -2
  96. package/dist/chunks/run-manager-N4UFWA2D.js +0 -2
  97. package/dist/chunks/utils-AUHCI4D5.js +0 -2
  98. package/dist/types-chunks/center-types.d-BBT122uJ.d.ts +0 -91
@@ -1,9 +1,9 @@
1
- import { bs as KodaXGoalState, a8 as AgentMessage, dv as StopHookFn, bM as KodaXSessionLineage, k as AgentActorStore, aC as AgentTurnExecutor, t as AgentBudgetPort, h as AgentActorClient, N as AgentExecutionResult, V as AgentExecutorPlaneBinding, by as KodaXJsonValue, bm as KodaXExtensionSessionRecord, f as Agent, dS as WorkflowIsolation, bn as KodaXExtensionSessionState, bD as KodaXSessionArtifactLedgerEntry, df as SessionErrorMetadata, bU as KodaXSessionScope, bV as KodaXSessionStorage, cj as MemoryContextIdentity, cv as MemoryPack, aK as AskUserQuestionOptions, aG as AskUserAnswer, aI as AskUserMultiOptions, dP as WorkflowEventCorrelation, aT as CompactionUpdate, e4 as WorkflowProcessEvent, dO as WorkflowEvent, cJ as MemoryReviewPlan, bA as KodaXMemoryOutcomeDigest, bb as Guardrail, aY as DiscoveredInstance, bw as KodaXInputArtifact, cK as MemoryReviewRunner } from './types.d-RdWRfUEs.js';
1
+ import { bz as KodaXGoalState, ab as AgentMessage, eg as StopHookFn, bU as KodaXSessionLineage, n as AgentActorStore, aF as AgentTurnExecutor, w as AgentBudgetPort, i as AgentActorOwner, h as AgentActorClient, Q as AgentExecutionResult, Y as AgentExecutorPlaneBinding, bF as KodaXJsonValue, bt as KodaXExtensionSessionRecord, f as Agent, eG as WorkflowIsolation, bu as KodaXExtensionSessionState, bL as KodaXSessionArtifactLedgerEntry, e0 as SessionErrorMetadata, c0 as KodaXSessionScope, c1 as KodaXSessionStorage, d2 as MemoryContextIdentity, de as MemoryPack, aN as AskUserQuestionOptions, aJ as AskUserAnswer, aL as AskUserMultiOptions, eD as WorkflowEventCorrelation, aX as CompactionUpdate, eU as WorkflowProcessEvent, eC as WorkflowEvent, dt as MemoryReviewPlan, bI as KodaXMemoryOutcomeDigest, bi as Guardrail, b2 as DiscoveredInstance, bD as KodaXInputArtifact, du as MemoryReviewRunner, eu as UnifiedLearningReviewRunner } from './types.d-BA-Jwpfs.js';
2
2
  import { a0 as KodaXTokenUsage, k as KodaXMessage, a1 as KodaXToolDefinition, a9 as KodaXWireReasoningEffort, U as KodaXTaskRoutingDecision, V as KodaXTaskType, W as KodaXTaskWorkIntent, Q as KodaXTaskComplexity, L as KodaXRiskLevel, h as KodaXHarnessProfile, f as KodaXExecutionMode, b as KodaXChildFanoutClass, F as KodaXReasoningMode, J as KodaXReviewScale } from './types.d-DIpZJKUl.js';
3
- import { d as SkillDynamicContextExecutor, I as ISkillRegistry } from './types.d-DCQVBqVn.js';
3
+ import { d as SkillDynamicContextExecutor, I as ISkillRegistry } from './types.d-BbtGlKZu.js';
4
4
  import { Diagnostic, Position, Location, Hover, DocumentSymbol, SymbolInformation, WorkspaceSymbol, CallHierarchyItem, CallHierarchyIncomingCall, CallHierarchyOutgoingCall } from 'vscode-languageserver-protocol';
5
5
  import { K as KodaXLlmTimeoutConfig, a as CostTracker } from './cost-tracker.d-BeaenODW.js';
6
- import { t as MemoryRecallRunner } from './types-LanCEDj8.js';
6
+ import { t as MemoryRecallRunner } from './types-D3g6XUQr.js';
7
7
  import { C as CapabilityKind, f as CapabilitySearchSnapshot, b as CapabilityResult } from './capability.d-K664nHOS.js';
8
8
  import { K as KodaXBaseProvider } from './base.d-4e74xDdy.js';
9
9
 
@@ -837,6 +837,8 @@ interface CodingActorSessionOptions {
837
837
  readonly store?: AgentActorStore;
838
838
  readonly executor?: AgentTurnExecutor;
839
839
  readonly budget?: AgentBudgetPort;
840
+ readonly owner?: AgentActorOwner;
841
+ readonly isOwnerAlive?: (owner: AgentActorOwner) => boolean | Promise<boolean>;
840
842
  }
841
843
  /** One Runtime-owned Actor tree for one KodaX session. */
842
844
  declare class CodingActorSession {
@@ -849,6 +851,8 @@ declare class CodingActorSession {
849
851
  initialize(): Promise<void>;
850
852
  attach(parentCtx: KodaXToolExecutionContext, options: KodaXOptions, callerPath?: string): AgentActorClient;
851
853
  rootControl(): AgentActorClient;
854
+ ownerId(): string | undefined;
855
+ ownsDurableFence(): boolean;
852
856
  createWorkflowOwner(parentPath: string, runId: string): Promise<AgentActorClient>;
853
857
  workflowOwnerSignal(ownerPath: string): AbortSignal;
854
858
  settleWorkflowOwner(ownerPath: string, state: 'completed' | 'failed' | 'interrupted', result: AgentExecutionResult & {
@@ -859,6 +863,8 @@ declare class CodingActorSession {
859
863
  registerTurnExecutor(key: string, executor: AgentTurnExecutor): () => void;
860
864
  waitForAgentCapacity(signal?: AbortSignal): Promise<boolean>;
861
865
  close(reason?: string): Promise<void>;
866
+ quiesce(reason?: string): Promise<void>;
867
+ disposeAfterStoreRemoval(reason?: string): void;
862
868
  }
863
869
  declare function createLocalCodingActorControl(parentCtx: KodaXToolExecutionContext, options: KodaXOptions): AgentActorClient;
864
870
  /** Runtime adapter for detached external Actor turns. The executor plane stays internal. */
@@ -871,7 +877,7 @@ declare function createExternalActorTurnExecutor(binding: AgentExecutorPlaneBind
871
877
  * configure / install / troubleshoot KodaX?" questions. Pure data + a
872
878
  * deterministic resolver — no RAG, no vector store, no network fetch.
873
879
  */
874
- type KodaXManualTopicId = 'overview' | 'license' | 'install' | 'quickstart' | 'providers' | 'custom-providers' | 'config' | 'permissions' | 'commands' | 'tools' | 'agents' | 'skills' | 'extensions' | 'mcp' | 'a2a' | 'repo-intelligence' | 'sessions' | 'compaction' | 'memory' | 'doctor' | 'sdk' | 'troubleshooting';
880
+ type KodaXManualTopicId = 'overview' | 'license' | 'install' | 'quickstart' | 'providers' | 'custom-providers' | 'config' | 'permissions' | 'sandbox' | 'commands' | 'tools' | 'agents' | 'skills' | 'extensions' | 'mcp' | 'a2a' | 'repo-intelligence' | 'sessions' | 'compaction' | 'memory' | 'doctor' | 'sdk' | 'troubleshooting';
875
881
  /** A pointer to the code/doc the topic is derived from (for traceability). */
876
882
  interface KodaXManualSource {
877
883
  readonly label: string;
@@ -1687,6 +1693,25 @@ interface KodaXWorkflowAgentDigestEvent {
1687
1693
  interface KodaXToolEventMeta extends KodaXActivityEventMeta {
1688
1694
  readonly toolId?: string;
1689
1695
  }
1696
+ type KodaXShellSandboxBackend = 'windows-restricted-user' | 'macos-seatbelt' | 'linux-bubblewrap' | 'unsupported';
1697
+ type KodaXShellSandboxObservation = {
1698
+ readonly version: 1;
1699
+ readonly state: 'applied';
1700
+ readonly backend: KodaXShellSandboxBackend;
1701
+ readonly policyId: 'kodax-workspace-shell-v1';
1702
+ } | {
1703
+ readonly version: 1;
1704
+ readonly state: 'fallback';
1705
+ readonly reason: 'not_ready' | 'prepare_failed' | 'backend_failed';
1706
+ readonly execution: 'normal_permission_policy';
1707
+ } | {
1708
+ readonly version: 1;
1709
+ readonly state: 'not_selected';
1710
+ };
1711
+ interface KodaXToolSandboxObservationUpdate {
1712
+ readonly id: string;
1713
+ readonly observation: KodaXShellSandboxObservation;
1714
+ }
1690
1715
  interface KodaXContextCompactionFinishedEvent extends Partial<KodaXLiveEventMeta> {
1691
1716
  readonly source: 'manual' | 'automatic_threshold' | 'physical_capacity';
1692
1717
  readonly tokensBefore: number;
@@ -1806,6 +1831,11 @@ interface KodaXEvents {
1806
1831
  id: string;
1807
1832
  message: string;
1808
1833
  }, meta?: KodaXToolEventMeta) => void;
1834
+ /**
1835
+ * Execution metadata for professional hosts. REPL history intentionally does
1836
+ * not render this internal containment state.
1837
+ */
1838
+ onToolSandboxObservation?: (update: KodaXToolSandboxObservationUpdate, meta?: KodaXToolEventMeta) => void;
1809
1839
  onToolInputDelta?: (toolName: string, partialJson: string, meta?: KodaXToolEventMeta) => void;
1810
1840
  onStreamEnd?: (meta?: KodaXActivityEventMeta) => void;
1811
1841
  /** Fired once when a child-agent run fully leaves the child executor. */
@@ -2035,12 +2065,17 @@ interface KodaXEvents {
2035
2065
  /** Semantic memory review plan produced from explicit user feedback. */
2036
2066
  onMemoryReview?: (plan: MemoryReviewPlan) => void;
2037
2067
  onMemoryNotice?: (notice: {
2068
+ readonly sessionId?: string;
2038
2069
  readonly episodeId: string;
2039
2070
  readonly summaries: readonly string[];
2040
2071
  readonly proposalIds: readonly string[];
2041
2072
  }) => void;
2042
- onMemoryOutcomeDigest?: (digest: KodaXMemoryOutcomeDigest) => void;
2073
+ onMemoryOutcomeDigest?: (digest: KodaXMemoryOutcomeDigest, metadata?: {
2074
+ readonly jobId?: string;
2075
+ }) => void;
2043
2076
  onMemoryReviewReceipt?: (receipt: {
2077
+ readonly sessionId?: string;
2078
+ readonly jobId?: string;
2044
2079
  readonly reviewKey: string;
2045
2080
  readonly proposalIds: readonly string[];
2046
2081
  readonly completedAt: string;
@@ -2093,7 +2128,10 @@ interface KodaXSessionOptions {
2093
2128
  * NOT also snapshot the session: `saveSessionSnapshot` early-returns so
2094
2129
  * the runner's flat full-rewrite `storage.save` can never race / clobber
2095
2130
  * the host's richer incremental writes (which regressed `activeEntryId`
2096
- * to the first round on resume).
2131
+ * to the first round on resume). Context-silent protocol facts may use the
2132
+ * host's optional atomic `storage.mutateLineage`; this never writes a stale
2133
+ * full session snapshot. A host using F263 durable Memory review facts must
2134
+ * provide that capability; those writes fail closed when it is absent.
2097
2135
  *
2098
2136
  * `storage` is still consulted for LOAD (resume / `resolveInitialMessages`
2099
2137
  * tier 2). When absent (print CLI, ACP, SDK headless), the runner remains
@@ -2729,7 +2767,35 @@ interface KodaXShellExecutionContract {
2729
2767
  };
2730
2768
  readonly probeTimeoutMs?: number;
2731
2769
  }
2770
+ interface KodaXShellSandboxPrepareInput {
2771
+ readonly toolCallId?: string;
2772
+ readonly toolInput: Readonly<Record<string, unknown>>;
2773
+ readonly command: string;
2774
+ readonly executable?: string;
2775
+ readonly args?: readonly string[];
2776
+ readonly cwd: string;
2777
+ readonly env: NodeJS.ProcessEnv;
2778
+ readonly windowsVerbatimArguments?: boolean;
2779
+ /** Caller cancellation while waiting for sandbox admission/preparation. */
2780
+ readonly signal?: AbortSignal;
2781
+ /** Absolute wall-clock deadline shared with the command timeout. */
2782
+ readonly deadlineAt?: number;
2783
+ readonly reportObservation?: (observation: KodaXShellSandboxObservation) => void;
2784
+ }
2785
+ interface KodaXPreparedShellSandboxInvocation {
2786
+ readonly executable: string;
2787
+ readonly args: readonly string[];
2788
+ readonly env: NodeJS.ProcessEnv;
2789
+ readonly windowsVerbatimArguments?: boolean;
2790
+ cleanup(): Promise<KodaXShellSandboxObservation | undefined>;
2791
+ }
2792
+ /** Runtime-owned OS sandbox broker for selected concrete shell calls. */
2793
+ interface KodaXShellSandbox {
2794
+ prepare(input: KodaXShellSandboxPrepareInput): Promise<KodaXPreparedShellSandboxInvocation | undefined>;
2795
+ }
2732
2796
  interface KodaXContextOptions {
2797
+ /** Runtime-owner config home used by Memory, review inbox, and Learned Area routing. */
2798
+ configHome?: string;
2733
2799
  /** Runtime-internal shared work ledger inherited by every descendant Agent run. */
2734
2800
  managedWorkBudget?: KodaXManagedWorkBudget;
2735
2801
  /** FEATURE_260 runtime-owned identity used for scoped memory reads. */
@@ -2787,6 +2853,8 @@ interface KodaXContextOptions {
2787
2853
  executionCwd?: string;
2788
2854
  /** Optional host-owned shell/environment resolution policy for command tools. */
2789
2855
  shellExecution?: KodaXShellExecutionContract;
2856
+ /** Runtime-owned OS sandbox broker; never accepted from serialized model input. */
2857
+ shellSandbox?: KodaXShellSandbox;
2790
2858
  /** Fail-closed host policy applied to every concrete file a read tool opens. */
2791
2859
  assertReadablePath?: (candidate: string) => void;
2792
2860
  /**
@@ -2827,6 +2895,30 @@ interface KodaXContextOptions {
2827
2895
  skillsPrompt?: string;
2828
2896
  /** Optional run-scoped registry used to pin and restrict Skill invocation. */
2829
2897
  skillRegistry?: ISkillRegistry;
2898
+ /** Runtime-owned complete formal-name inventory used to prevent learned Skill shadowing. */
2899
+ protectedFormalSkillNames?: readonly string[];
2900
+ /**
2901
+ * Opaque root-run binding used to correlate learned Skill usage with the
2902
+ * exact Memory episode produced by that run.
2903
+ *
2904
+ * @internal
2905
+ */
2906
+ learnedSkillBindingId?: string;
2907
+ /** Runtime-owner admission for exact learned Skill revisions. */
2908
+ admitLearnedSkillInvocation?: (input: {
2909
+ readonly sessionId: string;
2910
+ readonly capabilityId: string;
2911
+ readonly revision: number;
2912
+ readonly fingerprint: string;
2913
+ }) => Promise<{
2914
+ readonly invocationId: string;
2915
+ }>;
2916
+ /** Runtime-owner outcome correlation for learned Skill canaries. */
2917
+ completeLearnedSkillOutcomes?: (input: {
2918
+ readonly sessionId: string;
2919
+ readonly outcome: 'verified_success' | 'credible_negative' | 'inconclusive';
2920
+ readonly evidenceRefs: readonly string[];
2921
+ }) => Promise<void>;
2830
2922
  /** Remote-runtime broker for explicitly admitted, OS-sandboxed Skill scripts. */
2831
2923
  skillScriptRunner?: KodaXSkillScriptRunner;
2832
2924
  rawUserInput?: string;
@@ -3020,6 +3112,8 @@ interface KodaXOptions {
3020
3112
  context?: KodaXContextOptions;
3021
3113
  events?: KodaXEvents;
3022
3114
  memoryReviewer?: MemoryReviewRunner;
3115
+ /** One-call F263 reviewer. When present it replaces the memory-only reviewer for episode jobs. */
3116
+ learningReviewer?: UnifiedLearningReviewRunner;
3023
3117
  /** Optional host-owned semantic selector for sparse governed memory interventions. */
3024
3118
  memoryRecallRunner?: MemoryRecallRunner;
3025
3119
  extensionRuntime?: ExtensionRuntimeContract;
@@ -3387,6 +3481,24 @@ interface KodaXToolExecutionContext {
3387
3481
  readonly content: string;
3388
3482
  readonly evidenceRefs: readonly string[];
3389
3483
  } | undefined>;
3484
+ /**
3485
+ * Root-session-only submission channel for explicit user Memory intent.
3486
+ * The host validates an exact current-user quote and captures one intent for
3487
+ * end-of-episode governed submission; this callback never creates a durable
3488
+ * review job or writes Memory directly.
3489
+ */
3490
+ memoryIntent?: (input: {
3491
+ readonly operation: 'remember' | 'correct';
3492
+ readonly statement: string;
3493
+ readonly userQuote: string;
3494
+ }) => Promise<{
3495
+ readonly status: 'captured';
3496
+ readonly operation: 'remember' | 'correct';
3497
+ readonly evidenceRef: string;
3498
+ } | {
3499
+ readonly status: 'rejected';
3500
+ readonly reason: string;
3501
+ }>;
3390
3502
  /** Exact persisted history loader for the current root or isolated worker Session. */
3391
3503
  loadSessionHistory?: () => Promise<KodaXSessionLineage | null>;
3392
3504
  /** Git root directory - Git 鏍圭洰褰?*/
@@ -3427,12 +3539,18 @@ interface KodaXToolExecutionContext {
3427
3539
  skillDynamicContext?: KodaXSkillDynamicContextPolicy;
3428
3540
  /** Runtime-bound Skill registry; avoids process-global cross-session drift. */
3429
3541
  skillRegistry?: ISkillRegistry;
3542
+ /** Runtime-owner admission for exact learned Skill revisions. */
3543
+ admitLearnedSkillInvocation?: KodaXContextOptions['admitLearnedSkillInvocation'];
3430
3544
  /** Present only when the host admitted exact Skill scripts for this run. */
3431
3545
  skillScriptRunner?: KodaXSkillScriptRunner;
3432
3546
  /** Working directory used to resolve relative paths and execute shell commands. */
3433
3547
  executionCwd?: string;
3434
3548
  /** Validated shell execution policy inherited by native child runtimes. */
3435
3549
  shellExecution?: KodaXShellExecutionContract;
3550
+ /** Runtime-owned OS sandbox broker for selected concrete shell calls. */
3551
+ shellSandbox?: KodaXShellSandbox;
3552
+ /** Structured containment metadata; never model-visible or persisted as conversation text. */
3553
+ reportToolSandboxObservation?: (observation: KodaXShellSandboxObservation) => void;
3436
3554
  /**
3437
3555
  * Exact credential variable names owned by registered Providers.
3438
3556
  * Used only to remove non-standard `apiKeyEnv` names from child processes.
@@ -3881,5 +3999,5 @@ interface CreateBashPrefixExtractorOptions {
3881
3999
  */
3882
4000
  declare function createBashPrefixExtractor(opts: CreateBashPrefixExtractorOptions): BashPrefixExtractor;
3883
4001
 
3884
- export { ALWAYS_RESIDENT_TOOL_NAMES as A, BASH_POLICY_SPEC as B, LSP_SERVERS as aW, LspService as aY, buildGoalRuntimeBinding as bC, consumeCompactionCooldown as bD, createBashPrefixExtractor as bE, createCompactionAntiThrashState as bF, createExternalActorTurnExecutor as bG, createLocalCodingActorControl as bH, createRuntimeContextBudgetSnapshot as bI, decideWorkflowInvocation as bJ, drainPendingSwaps as bK, estimateToolSchemaTokens as bL, extractCommandPrefix as bM, getDefaultLspService as bN, hasExplicitNaturalLanguageWorkflowIntent as bO, hasPendingSwap as bP, makeDisabledGoalToolsContext as bQ, normalizeKodaXAgentMode as bR, planToolExposure as bS, providerResilienceConfigFromTimeouts as bT, recordCompactionSavings as bU, resolveConstructedAgent as bV, shouldSkipLlmCompaction as bW, shutdownDefaultLspService as bX, withGoalBeforeNextTurn as bY, withGoalStopHook as bZ, workflowStartOutcomeConsumesTurn as b_, CodingActorSession as d };
3885
- export type { KodaXManualTopicInput as $, CapabilityRuntimeContract as C, DiagnosticsRequest as D, ExtensionRuntimeContract as E, FailureStage as F, GoalBlockedResult as G, KodaXChildContextBundle as H, KodaXChildExecutionResult as I, KodaXCompactionOverride as J, KodaXActivityEventMeta as K, KodaXContextCompactionFinishedEvent as L, KodaXContextIdentity as M, KodaXContextOptions as N, KodaXContextTokenSnapshot as O, KodaXEffectiveTaskConfig as P, KodaXEvents as Q, KodaXLiveEventMeta as R, KodaXManagedBudgetSnapshot as S, KodaXManagedProtocolPayload as T, KodaXManagedTask as U, KodaXManagedTaskRuntimeState as V, KodaXManagedTaskStatusEvent as W, KodaXManualIndexTopic as X, KodaXManualSource as Y, KodaXManualTopic as Z, KodaXManualTopicId as _, BashPrefixExtractor as a, ProviderRecoveryEvent as a$, KodaXMemoryStrategy as a0, KodaXOptions as a1, KodaXOrchestrationVerdict as a2, KodaXParentReductionContract as a3, KodaXPromptCacheDiagnosticEvent as a4, KodaXProviderPolicyHints as a5, KodaXRepoIntelligenceCapability as a6, KodaXRepoIntelligenceMode as a7, KodaXRepoIntelligenceResolvedMode as a8, KodaXRepoIntelligenceTrace as a9, KodaXTaskRole as aA, KodaXTaskRoleAssignment as aB, KodaXTaskStatus as aC, KodaXTaskSurface as aD, KodaXTaskToolPolicy as aE, KodaXTaskVerificationContract as aF, KodaXTaskVerificationCriterion as aG, KodaXTaskWorkItem as aH, KodaXTimeoutConfig as aI, KodaXToolEventMeta as aJ, KodaXToolExecutionContext as aK, KodaXToolVisibilityMeta as aL, KodaXToolVisibilityPolicy as aM, KodaXTurnCompletedEvent as aN, KodaXTurnDeliveryKind as aO, KodaXTurnFailedEvent as aP, KodaXTurnStartedEvent as aQ, KodaXVerificationScorecard as aR, KodaXVerificationScorecardCriterion as aS, KodaXWorkflowAgentDigestEvent as aT, KodaXWorkflowEventMeta as aU, KodaXWorkflowTimeoutConfig as aV, LspServerInfo as aX, LspServiceConfig as aZ, ProviderExecutionState as a_, KodaXRepoIntelligenceTraceEvent as aa, KodaXRepoRoutingSignals as ab, KodaXResult as ac, KodaXRoleRoundSummary as ad, KodaXRuntimeVerificationContract as ae, KodaXSelfManualConfig as af, KodaXSessionControl as ag, KodaXSessionMutators as ah, KodaXSessionOptions as ai, KodaXShellExecutionContract as aj, KodaXShellKind as ak, KodaXShellProfileMode as al, KodaXSidecarMessageEvent as am, KodaXSkillDynamicContextPolicy as an, KodaXSkillInvocationContext as ao, KodaXSkillMap as ap, KodaXSkillProjectionConfidence as aq, KodaXSkillScriptInputFile as ar, KodaXSkillScriptOutputFile as as, KodaXSkillScriptRunInput as at, KodaXSkillScriptRunner as au, KodaXTaskCapabilityHint as av, KodaXTaskContract as aw, KodaXTaskEvidenceArtifact as ax, KodaXTaskEvidenceBundle as ay, KodaXTaskEvidenceEntry as az, BashPrefixResult as b, ProviderResilienceConfig as b0, ProviderResiliencePolicy as b1, RecoveryAction as b2, RecoveryDecision as b3, RecoveryLadderStep as b4, RecoveryResult as b5, ResilienceClassification as b6, ResilienceErrorClass as b7, ResolveKodaXManualInput as b8, ResolveKodaXManualOptions as b9, WorkflowToolHostResult as bA, WorkflowToolHostStartResult as bB, ResolveKodaXManualResult as ba, RuntimeCompactionSkippedEvent as bb, RuntimeContextBudgetBreakdown as bc, RuntimeContextBudgetRecommendation as bd, RuntimeContextBudgetSnapshot as be, RuntimeContextBudgetSnapshotInput as bf, RuntimeContextOptimizationProfile as bg, RuntimeContextPressure as bh, RuntimeDefaultsSnapshot as bi, RuntimeToolExposureDecision as bj, RuntimeToolExposureMode as bk, RuntimeToolExposurePlan as bl, RuntimeToolExposurePlanInput as bm, RuntimeToolExposureReason as bn, TodoItem as bo, TodoList as bp, TodoStatus as bq, ToolSideEffect as br, WorkflowHostPolicy as bs, WorkflowInvocationAction as bt, WorkflowInvocationPolicyDecision as bu, WorkflowInvocationPolicyInput as bv, WorkflowInvocationSource as bw, WorkflowStartOutcome as bx, WorkflowToolHost as by, WorkflowToolHostInlineInput as bz, BoundExtensionRuntimeController as c, CodingActorSessionOptions as e, CompactionAntiThrashConfig as f, CompactionAntiThrashState as g, CompactionSavingsDecision as h, CompactionSavingsSample as i, CompactionSkipReason as j, CreateBashPrefixExtractorOptions as k, ExtractCommandPrefixOptions as l, GoalCompleteResult as m, GoalCreateInput as n, GoalLifecycleContext as o, GoalRuntimeBinding as p, GoalRuntimeBindingDeps as q, GoalToolsContext as r, KodaXActorHost as s, KodaXAgentMode as t, KodaXAgentProfile as u, KodaXAgentScope as v, KodaXBudgetDisclosureZone as w, KodaXBudgetExtensionRequest as x, KodaXCanonicalAgentMode as y, KodaXChildAgentResult as z };
4002
+ export { ALWAYS_RESIDENT_TOOL_NAMES as A, BASH_POLICY_SPEC as B, resolveConstructedAgent as b$, LSP_SERVERS as b0, LspService as b2, buildGoalRuntimeBinding as bI, consumeCompactionCooldown as bJ, createBashPrefixExtractor as bK, createCompactionAntiThrashState as bL, createExternalActorTurnExecutor as bM, createLocalCodingActorControl as bN, createRuntimeContextBudgetSnapshot as bO, decideWorkflowInvocation as bP, drainPendingSwaps as bQ, estimateToolSchemaTokens as bR, extractCommandPrefix as bS, getDefaultLspService as bT, hasExplicitNaturalLanguageWorkflowIntent as bU, hasPendingSwap as bV, makeDisabledGoalToolsContext as bW, normalizeKodaXAgentMode as bX, planToolExposure as bY, providerResilienceConfigFromTimeouts as bZ, recordCompactionSavings as b_, shouldSkipLlmCompaction as c0, shutdownDefaultLspService as c1, withGoalBeforeNextTurn as c2, withGoalStopHook as c3, workflowStartOutcomeConsumesTurn as c4, CodingActorSession as d };
4003
+ export type { KodaXManualTopicInput as $, CapabilityRuntimeContract as C, DiagnosticsRequest as D, ExtensionRuntimeContract as E, FailureStage as F, GoalBlockedResult as G, KodaXChildContextBundle as H, KodaXChildExecutionResult as I, KodaXCompactionOverride as J, KodaXActivityEventMeta as K, KodaXContextCompactionFinishedEvent as L, KodaXContextIdentity as M, KodaXContextOptions as N, KodaXContextTokenSnapshot as O, KodaXEffectiveTaskConfig as P, KodaXEvents as Q, KodaXLiveEventMeta as R, KodaXManagedBudgetSnapshot as S, KodaXManagedProtocolPayload as T, KodaXManagedTask as U, KodaXManagedTaskRuntimeState as V, KodaXManagedTaskStatusEvent as W, KodaXManualIndexTopic as X, KodaXManualSource as Y, KodaXManualTopic as Z, KodaXManualTopicId as _, BashPrefixExtractor as a, KodaXWorkflowTimeoutConfig as a$, KodaXMemoryStrategy as a0, KodaXOptions as a1, KodaXOrchestrationVerdict as a2, KodaXParentReductionContract as a3, KodaXPreparedShellSandboxInvocation as a4, KodaXPromptCacheDiagnosticEvent as a5, KodaXProviderPolicyHints as a6, KodaXRepoIntelligenceCapability as a7, KodaXRepoIntelligenceMode as a8, KodaXRepoIntelligenceResolvedMode as a9, KodaXTaskCapabilityHint as aA, KodaXTaskContract as aB, KodaXTaskEvidenceArtifact as aC, KodaXTaskEvidenceBundle as aD, KodaXTaskEvidenceEntry as aE, KodaXTaskRole as aF, KodaXTaskRoleAssignment as aG, KodaXTaskStatus as aH, KodaXTaskSurface as aI, KodaXTaskToolPolicy as aJ, KodaXTaskVerificationContract as aK, KodaXTaskVerificationCriterion as aL, KodaXTaskWorkItem as aM, KodaXTimeoutConfig as aN, KodaXToolEventMeta as aO, KodaXToolExecutionContext as aP, KodaXToolSandboxObservationUpdate as aQ, KodaXToolVisibilityMeta as aR, KodaXToolVisibilityPolicy as aS, KodaXTurnCompletedEvent as aT, KodaXTurnDeliveryKind as aU, KodaXTurnFailedEvent as aV, KodaXTurnStartedEvent as aW, KodaXVerificationScorecard as aX, KodaXVerificationScorecardCriterion as aY, KodaXWorkflowAgentDigestEvent as aZ, KodaXWorkflowEventMeta as a_, KodaXRepoIntelligenceTrace as aa, KodaXRepoIntelligenceTraceEvent as ab, KodaXRepoRoutingSignals as ac, KodaXResult as ad, KodaXRoleRoundSummary as ae, KodaXRuntimeVerificationContract as af, KodaXSelfManualConfig as ag, KodaXSessionControl as ah, KodaXSessionMutators as ai, KodaXSessionOptions as aj, KodaXShellExecutionContract as ak, KodaXShellKind as al, KodaXShellProfileMode as am, KodaXShellSandbox as an, KodaXShellSandboxBackend as ao, KodaXShellSandboxObservation as ap, KodaXShellSandboxPrepareInput as aq, KodaXSidecarMessageEvent as ar, KodaXSkillDynamicContextPolicy as as, KodaXSkillInvocationContext as at, KodaXSkillMap as au, KodaXSkillProjectionConfidence as av, KodaXSkillScriptInputFile as aw, KodaXSkillScriptOutputFile as ax, KodaXSkillScriptRunInput as ay, KodaXSkillScriptRunner as az, BashPrefixResult as b, LspServerInfo as b1, LspServiceConfig as b3, ProviderExecutionState as b4, ProviderRecoveryEvent as b5, ProviderResilienceConfig as b6, ProviderResiliencePolicy as b7, RecoveryAction as b8, RecoveryDecision as b9, WorkflowInvocationPolicyDecision as bA, WorkflowInvocationPolicyInput as bB, WorkflowInvocationSource as bC, WorkflowStartOutcome as bD, WorkflowToolHost as bE, WorkflowToolHostInlineInput as bF, WorkflowToolHostResult as bG, WorkflowToolHostStartResult as bH, RecoveryLadderStep as ba, RecoveryResult as bb, ResilienceClassification as bc, ResilienceErrorClass as bd, ResolveKodaXManualInput as be, ResolveKodaXManualOptions as bf, ResolveKodaXManualResult as bg, RuntimeCompactionSkippedEvent as bh, RuntimeContextBudgetBreakdown as bi, RuntimeContextBudgetRecommendation as bj, RuntimeContextBudgetSnapshot as bk, RuntimeContextBudgetSnapshotInput as bl, RuntimeContextOptimizationProfile as bm, RuntimeContextPressure as bn, RuntimeDefaultsSnapshot as bo, RuntimeToolExposureDecision as bp, RuntimeToolExposureMode as bq, RuntimeToolExposurePlan as br, RuntimeToolExposurePlanInput as bs, RuntimeToolExposureReason as bt, TodoItem as bu, TodoList as bv, TodoStatus as bw, ToolSideEffect as bx, WorkflowHostPolicy as by, WorkflowInvocationAction as bz, BoundExtensionRuntimeController as c, CodingActorSessionOptions as e, CompactionAntiThrashConfig as f, CompactionAntiThrashState as g, CompactionSavingsDecision as h, CompactionSavingsSample as i, CompactionSkipReason as j, CreateBashPrefixExtractorOptions as k, ExtractCommandPrefixOptions as l, GoalCompleteResult as m, GoalCreateInput as n, GoalLifecycleContext as o, GoalRuntimeBinding as p, GoalRuntimeBindingDeps as q, GoalToolsContext as r, KodaXActorHost as s, KodaXAgentMode as t, KodaXAgentProfile as u, KodaXAgentScope as v, KodaXBudgetDisclosureZone as w, KodaXBudgetExtensionRequest as x, KodaXCanonicalAgentMode as y, KodaXChildAgentResult as z };
@@ -1,5 +1,5 @@
1
1
  import { k as KodaXMessage } from './types.d-DIpZJKUl.js';
2
- import { a8 as AgentMessage, de as SessionEntry, dc as Session, dg as SessionExtension, bM as KodaXSessionLineage, by as KodaXJsonValue, aP as CompactionDetails, bl as KodaXCompactMemorySeed, bI as KodaXSessionEntry, bW as KodaXSessionTreeNode, bL as KodaXSessionLabelEntry, bK as KodaXSessionGoalEntry, bF as KodaXSessionClientNoticeEntry, bS as KodaXSessionRewindMarkerEntry, bN as KodaXSessionMemoryOutcomeDigestEntry, bO as KodaXSessionMemoryReviewReceiptEntry, bR as KodaXSessionNavigationOptions, bD as KodaXSessionArtifactLedgerEntry, b9 as FileOperations, dV as WorkflowMeta, dW as WorkflowModelHint, dX as WorkflowModule } from './types.d-RdWRfUEs.js';
2
+ import { ab as AgentMessage, d$ as SessionEntry, dZ as Session, e1 as SessionExtension, bU as KodaXSessionLineage, bF as KodaXJsonValue, aT as CompactionDetails, bs as KodaXCompactMemorySeed, bQ as KodaXSessionEntry, c2 as KodaXSessionTreeNode, bT as KodaXSessionLabelEntry, bS as KodaXSessionGoalEntry, bN as KodaXSessionClientNoticeEntry, b_ as KodaXSessionRewindMarkerEntry, bV as KodaXSessionMemoryOutcomeDigestEntry, bW as KodaXSessionMemoryReviewReceiptEntry, bZ as KodaXSessionNavigationOptions, bL as KodaXSessionArtifactLedgerEntry, bg as FileOperations, eJ as WorkflowMeta, eK as WorkflowModelHint, eL as WorkflowModule } from './types.d-BA-Jwpfs.js';
3
3
 
4
4
  /**
5
5
  * @kodax-ai/agent Constants
@@ -1,4 +1,4 @@
1
- import { bb as Guardrail, d6 as RunnerToolCall, f as Agent, a8 as AgentMessage, d9 as RunnerToolResult, dk as Span } from './types.d-RdWRfUEs.js';
1
+ import { bi as Guardrail, dT as RunnerToolCall, f as Agent, ab as AgentMessage, dW as RunnerToolResult, e5 as Span } from './types.d-BA-Jwpfs.js';
2
2
 
3
3
  /**
4
4
  * Guardrail Runtime — FEATURE_085 (v0.7.26).
@@ -1,8 +1,10 @@
1
1
  import { b as McpServersConfig, M as McpConnectMode, a as McpServerConfig, c as McpTransportKind } from './config.d-CJy1WENT.js';
2
2
  import { K as KodaXBaseProvider } from './base.d-4e74xDdy.js';
3
3
  import { a as CostTracker } from './cost-tracker.d-BeaenODW.js';
4
- import { d6 as RunnerToolCall } from './types.d-RdWRfUEs.js';
5
- import { d as ToolGuardrail } from './guardrail.d-CJx9RRd3.js';
4
+ import { dT as RunnerToolCall } from './types.d-BA-Jwpfs.js';
5
+ import { d as ToolGuardrail } from './guardrail.d-BRE_ErEj.js';
6
+ import { k as KodaXMessage } from './types.d-DIpZJKUl.js';
7
+ import { S as SideQueryDiagnostics } from './side-query.d-DTuLPcC5.js';
6
8
 
7
9
  /**
8
10
  * FEATURE_200 Phase F (v0.7.45) — MCP domain types extracted from types.ts.
@@ -241,6 +243,157 @@ interface SignalCollector {
241
243
  */
242
244
  declare function collectAllSignals(call: RunnerToolCall, projectRoot: string, collectors: readonly SignalCollector[], executionCwd?: string): readonly ToolCallSignal[];
243
245
 
246
+ interface PermissionIntentEvidence {
247
+ readonly status: 'complete' | 'targeted' | 'missing';
248
+ /** Latest genuine user request, kept separate as the authoritative intent. */
249
+ readonly currentUserContent?: string;
250
+ readonly currentUserContentTruncated?: boolean;
251
+ readonly content: string;
252
+ readonly sourceBytes: number;
253
+ readonly includedBytes: number;
254
+ readonly omittedBytes: number;
255
+ readonly sha256: string;
256
+ }
257
+
258
+ /**
259
+ * Classifier Projection Helpers — FEATURE_092 (v0.7.33)
260
+ *
261
+ * Typed tools implement `toClassifierInput(input): string` to project their
262
+ * input into a compact action the auto-mode classifier evaluates. Runtime
263
+ * registration supplies a fail-closed semantic fallback for legacy JavaScript,
264
+ * extension, and constructed tools that lack a trusted projector.
265
+ *
266
+ * ============== EXAMPLES BY CATEGORY ==============
267
+ *
268
+ * --- FILE OPERATIONS (path + size, never raw contents) ---
269
+ * write.ts: (i) => `Write ${i.path} (${i.content.length} bytes)`
270
+ * edit.ts: (i) => `Edit ${i.path} [${describeEdit(i)}]`
271
+ * multi-edit: (i) => `MultiEdit ${i.path}: ${i.edits.length} edits`
272
+ *
273
+ * --- SHELL / EXEC (command verbatim, ignore noise fields) ---
274
+ * bash.ts: (i) => `Bash: ${i.command}`
275
+ *
276
+ * --- NETWORK (URL is THE risk surface) ---
277
+ * web_fetch: (i) => `WebFetch ${i.url}`
278
+ *
279
+ * --- CHILD AGENT SPAWN (routing + execution controls) ---
280
+ * spawn_agent: objective size + scope/read_only/isolation/provider/model
281
+ *
282
+ * --- MCP CALLS (semantic fields + shape-only unknowns) ---
283
+ * mcp_call: (i) => mcpToClassifierInput(i.server, i.tool, i.input)
284
+ *
285
+ * --- READ-ONLY (Tier 1 — fully skipped) ---
286
+ * read.ts: () => ''
287
+ * grep.ts: () => ''
288
+ * glob.ts: () => ''
289
+ *
290
+ * --- UNKNOWN / CONSTRUCTED (semantic fail-closed fallback) ---
291
+ * extension: (i) => safeFallbackToClassifierInput(name, i)
292
+ *
293
+ * ============== ANTI-PATTERNS ==============
294
+ *
295
+ * ❌ JSON.stringify(input) as default
296
+ * → leaks raw content; hard for LLM to scan
297
+ *
298
+ * ❌ Returning input.description / input.rationale verbatim
299
+ * → these are LLM-emitted, manipulable; classifier should see facts
300
+ *
301
+ * ❌ Including raw file contents in Write/Edit projections
302
+ * → privacy + token cost; use bytes/line count as proxy
303
+ *
304
+ * ❌ Returning '' for a high-risk tool to "skip the classifier"
305
+ * → defeats Tier 1's "safe-only" semantics
306
+ *
307
+ * ❌ Truncating without indicating it ('foo' instead of 'foo…')
308
+ * → classifier may make decisions on false-complete information
309
+ */
310
+ type ClassifierToolProjectionResolver = (toolName: string) => ((input: unknown) => string) | undefined;
311
+
312
+ /**
313
+ * Auto-Mode Classifier Orchestrator — FEATURE_092 Phase 2b.3 (v0.7.33).
314
+ *
315
+ * Wires the classifier prompt + sideQuery + output parser into a single
316
+ * `classify(...)` call. Caller supplies the rules, transcript, and the
317
+ * tool-call action being classified; gets back a `ClassifyDecision`.
318
+ *
319
+ * Failure → decision mapping:
320
+ *
321
+ * sideQuery.stopReason parsedOutput → ClassifyDecision
322
+ * ───────────────────────────────────────────────────────
323
+ * end_turn / max_tokens block → confirm (with reason)
324
+ * end_turn / max_tokens allow → allow
325
+ * end_turn / max_tokens unparseable → retry, then failure
326
+ * end_turn / max_tokens + tool_use → retry, then failure
327
+ * (sideQuery returns stopReason='error' here)
328
+ * timeout — → retry, then failure
329
+ * aborted — → throw AbortError to caller
330
+ * error — → retry, then failure
331
+ *
332
+ * Every non-abort failure receives one immediate retry. The caller applies
333
+ * its configured safety fallback after the second failure; a valid model
334
+ * concern always means "ask the user", never a direct hard block.
335
+ */
336
+
337
+ interface ClassifyOptions {
338
+ readonly provider: KodaXBaseProvider;
339
+ readonly model: string;
340
+ readonly rules: AutoRules;
341
+ readonly claudeMd?: string;
342
+ readonly transcript: readonly KodaXMessage[];
343
+ readonly action: string;
344
+ readonly intentEvidence?: PermissionIntentEvidence;
345
+ /** Resolve canonical per-tool projections for safe historical context. */
346
+ readonly getToolProjection?: ClassifierToolProjectionResolver;
347
+ /**
348
+ * FEATURE_158 (v0.7.39): static-analysis signals forwarded to the
349
+ * classifier prompt. Empty / undefined preserves the FEATURE_092 prompt
350
+ * shape (no `<signals>` block emitted). When supplied, the classifier
351
+ * sees signals between `<transcript>` and `<action>` as informational
352
+ * input — not verdicts.
353
+ */
354
+ readonly signals?: readonly ToolCallSignal[];
355
+ readonly timeoutMs?: number;
356
+ readonly abortSignal?: AbortSignal;
357
+ readonly costTracker?: CostTracker;
358
+ /**
359
+ * Optional setter — invoked once after `sideQuery` returns when the
360
+ * classifier successfully recorded its token usage. The CostTracker is
361
+ * immutable, so `sideQuery` produces a fresh tracker copy with the new
362
+ * record; without this setter the recorded call is silently dropped.
363
+ * Wired by the AutoModeToolGuardrail so the agent's tracker accumulates
364
+ * classifier calls under role='auto_mode'.
365
+ */
366
+ readonly setCostTracker?: (next: CostTracker) => void;
367
+ }
368
+ type ClassifierFailureKind = 'timeout' | 'provider_error' | 'contract_error' | 'input_budget';
369
+ type ClassifierAttemptOutcome = 'allow' | 'confirm' | ClassifierFailureKind;
370
+ interface ClassifierAttemptDiagnostics {
371
+ readonly attempt: number;
372
+ readonly outcome: ClassifierAttemptOutcome;
373
+ readonly diagnostics?: SideQueryDiagnostics;
374
+ }
375
+ interface ClassifyDecisionDetails {
376
+ readonly reason: string;
377
+ /** Structured request metadata only; never includes prompt or response text. */
378
+ readonly diagnostics?: SideQueryDiagnostics;
379
+ readonly attempts: readonly ClassifierAttemptDiagnostics[];
380
+ }
381
+ type ClassifyDecision = ({
382
+ readonly kind: 'allow';
383
+ } & ClassifyDecisionDetails) | ({
384
+ readonly kind: 'confirm';
385
+ } & ClassifyDecisionDetails) | ({
386
+ readonly kind: 'failure';
387
+ readonly failureKind: ClassifierFailureKind;
388
+ } & ClassifyDecisionDetails);
389
+ /**
390
+ * The deadline includes connection setup, provider-side queueing, inference,
391
+ * and any Retry-After/backoff handled by the provider adapter. Keep it bounded
392
+ * so infrastructure failure degrades to an explicit user decision.
393
+ */
394
+ declare const DEFAULT_CLASSIFIER_TIMEOUT_MS = 20000;
395
+ declare function classify(opts: ClassifyOptions): Promise<ClassifyDecision>;
396
+
244
397
  /**
245
398
  * Denial Tracker — FEATURE_092 Phase 2b.4 (v0.7.33).
246
399
  *
@@ -365,18 +518,19 @@ declare function checkAbsoluteDeny(call: RunnerToolCall, projectRoot: string, ex
365
518
  *
366
519
  * Decision flow (per design doc "三层权限金字塔"):
367
520
  *
368
- * 1. Tier-0 deterministic deny block
369
- * 2. Tool projection is '' (Tier 1) → allow (zero token cost)
370
- * 3. Engine is rules → deterministic Tier 2, otherwise user confirms
371
- * 4. denial/circuit threshold engine downgrade, then escalate
372
- * 5. classify(...) sideQuery
373
- * allow → allow (record allow → reset consecutive)
374
- * block block + reason (record block)
375
- * escalate escalate + reason (record error)
376
- * AbortError thrown re-throw (propagate user cancel)
521
+ * 1. Tier-0 deterministic critical match user confirmation
522
+ * 2. exact safe read/workspace-temp effect → allow (zero token cost)
523
+ * 3. Tool projection is '' (Tier 1) → allow
524
+ * 4. Engine is rules deterministic Tier 2, otherwise user confirms
525
+ * 5. degraded classifier infrastructure → Accept-edits fallback
526
+ * 6. classify(...) sideQuery
527
+ * allow allow (record allow → reset consecutive)
528
+ * confirm user confirmation (record concern)
529
+ * failure Accept-edits fallback (record error)
530
+ * AbortError thrown → re-throw (propagate user cancel)
377
531
  *
378
532
  * State (mutable, session-scoped):
379
- * - engine: 'llm' | 'rules' (starts at 'llm', downgrades on threshold)
533
+ * - engine: 'llm' | 'rules' (user-selected; classifier health never changes it)
380
534
  * - denialTracker (immutable type, swapped on each event)
381
535
  * - circuitBreaker (immutable type, swapped on each event)
382
536
  *
@@ -402,15 +556,20 @@ interface AutoModeSharedState {
402
556
  * User answer for an escalated tool-call. The guardrail translates this into
403
557
  * the actual `GuardrailVerdict` returned to the Runner. `'block'` preserves
404
558
  * the original escalation reason as the verdict reason so downstream consumers
405
- * see why the tool was blocked.
559
+ * see why the tool was blocked. `'timeout'` reports that the action was not
560
+ * executed and gives the main model a bounded recovery instruction.
406
561
  */
407
- type AutoModeAskUserVerdict = 'allow' | 'block';
562
+ type AutoModeAskUserVerdict = 'allow' | 'block' | 'timeout';
563
+ interface AutoModeDecisionDiagnostics {
564
+ readonly source: 'classifier_confirm' | 'classifier_failure' | 'classifier_circuit_breaker' | 'configuration';
565
+ readonly classifierFailureKind?: ClassifierFailureKind;
566
+ readonly classifierAttempts?: readonly ClassifierAttemptDiagnostics[];
567
+ }
408
568
  /**
409
- * Optional REPL-supplied prompt callback for the 6 escalate paths in
410
- * `beforeTool` (engine-downgraded, denial-threshold-just-crossed,
411
- * breaker-just-tripped, classifier-error, classifier-decision-escalate,
412
- * provider-not-configured). When supplied, the guardrail calls this and
413
- * translates the user's answer into `'allow'` or `'block'`. When NOT
569
+ * Optional REPL-supplied prompt callback for calls that require a human
570
+ * decision (rules escalation, classifier concern/failure, or configuration
571
+ * failure). When supplied, the guardrail calls this and
572
+ * translates the user's answer into allow/block/timeout semantics. When NOT
414
573
  * supplied, the guardrail returns `'escalate'` as before — the Runner will
415
574
  * then throw `GuardrailEscalateError` (preserves backward compat with
416
575
  * SDK-side guardrail consumers that have no askUser surface).
@@ -425,7 +584,7 @@ type AutoModeAskUser = (call: RunnerToolCall, reason: string,
425
584
  * keep working. REPL uses these to render Scope/Risk labels on the
426
585
  * confirm dialog (replacing the input-marker path from FEATURE_066).
427
586
  */
428
- signals?: readonly ToolCallSignal[]) => Promise<AutoModeAskUserVerdict>;
587
+ signals?: readonly ToolCallSignal[], diagnostics?: AutoModeDecisionDiagnostics) => Promise<AutoModeAskUserVerdict>;
429
588
  interface AutoModeRulesContext {
430
589
  readonly projectRoot: string;
431
590
  readonly executionCwd: string;
@@ -498,6 +657,15 @@ interface AutoModeGuardrailConfig {
498
657
  * paths. See `AutoModeAskUser` for semantics.
499
658
  */
500
659
  readonly askUser?: AutoModeAskUser;
660
+ /**
661
+ * Runtime-owned Accept-edits fallback used only when classifier
662
+ * infrastructure or its response contract fails.
663
+ */
664
+ readonly allowOnClassifierFailure?: (call: RunnerToolCall) => boolean | Promise<boolean>;
665
+ /** Whether ordinary bash calls can be enforced by an OS workspace sandbox. */
666
+ readonly workspaceShellSandboxAvailable?: boolean;
667
+ /** Mint one exact bash call for workspace-sandboxed execution. */
668
+ readonly admitWorkspaceSandboxCall?: (call: RunnerToolCall, review: AutoModePermissionReview) => void;
501
669
  /**
502
670
  * Runtime-owned deterministic Tier-2 evaluator. It is injected rather than
503
671
  * implemented in @kodax/coding because canonical path and shell-AST helpers
@@ -544,12 +712,11 @@ interface AutoModeGuardrailConfig {
544
712
  */
545
713
  readonly getCostTracker?: () => CostTracker | undefined;
546
714
  readonly setCostTracker?: (t: CostTracker) => void;
547
- /** Optional logger for engine-downgrade and config warnings. */
715
+ /** Optional logger for classifier-health and configuration warnings. */
548
716
  readonly log?: (level: 'info' | 'warn', msg: string) => void;
549
717
  /**
550
- * Fired whenever the active engine changes both on automatic downgrades
551
- * (denial threshold / circuit breaker) AND on manual `setEngine(...)`
552
- * calls. UI surfaces (status bar engine indicator, slash-command
718
+ * Fired whenever the active engine changes through `setEngine(...)`.
719
+ * UI surfaces (status bar engine indicator, slash-command
553
720
  * confirmations) subscribe here so the displayed engine stays in sync
554
721
  * with the guardrail's internal state without the user having to trigger
555
722
  * another mode toggle just to refresh the bar.
@@ -558,8 +725,8 @@ interface AutoModeGuardrailConfig {
558
725
  /**
559
726
  * Optional shared state for subagent threshold-bypass defense
560
727
  * (design doc "防绕阈值"). When supplied, the parent and child
561
- * guardrails reference the SAME object — engine downgrades and
562
- * tracker advances are visible across the session boundary.
728
+ * guardrails reference the SAME object — engine changes and tracker
729
+ * advances are visible across the session boundary.
563
730
  */
564
731
  readonly sharedState?: AutoModeSharedState;
565
732
  /**
@@ -625,8 +792,8 @@ interface AutoModeGuardrailConfig {
625
792
  * (late-verdict adoption). The window therefore only controls "fast path
626
793
  * vs wait", never "dialog vs no dialog": an `allow` never surfaces a
627
794
  * confirm dialog regardless of how long the classifier takes, and only an
628
- * `escalate` verdict (explicit LLM escalation, classifier timeout, or infra
629
- * error — all mapped to `escalate` by classify()) reaches the user.
795
+ * confirmation/failure verdict reaches the configured user or Accept-edits
796
+ * fallback path.
630
797
  * The background classifier's cost is settled exactly once inside
631
798
  * classify(), so awaiting it after window expiry does not double-count.
632
799
  *
@@ -645,6 +812,7 @@ interface AutoModeGuardrailConfig {
645
812
  */
646
813
  interface AutoModeStats {
647
814
  readonly engine: AutoModeEngine;
815
+ readonly classifierHealth: 'healthy' | 'degraded';
648
816
  readonly classifierModel?: string;
649
817
  readonly denials: DenialTracker;
650
818
  readonly breaker: CircuitBreaker;
@@ -656,19 +824,17 @@ interface AutoModeToolGuardrail extends ToolGuardrail {
656
824
  getStats(): AutoModeStats;
657
825
  /**
658
826
  * Manually set the engine. Used by `/auto-engine` slash command to flip
659
- * back to 'llm' after an automatic downgrade or to flip to 'rules' for
660
- * manual testing. The downgrade thresholds still operate normally — a
661
- * subsequent threshold cross will downgrade again.
827
+ * between 'llm' and 'rules' after an explicit user or host choice.
662
828
  */
663
829
  setEngine(engine: AutoModeEngine): void;
664
830
  /** Test-only alias for getEngine(). Backward-compat for test files. */
665
831
  getEngineForTest(): AutoModeEngine;
666
832
  /** Test-only alias for getStats(). Backward-compat for test files. */
667
833
  getStatsForTest(): AutoModeStats;
668
- /** Test-only override: swap the provider mid-test (for downgrade scenarios). */
834
+ /** Test-only override: swap the provider mid-test. */
669
835
  setProviderForTest(provider: KodaXBaseProvider): void;
670
836
  }
671
837
  declare function createAutoModeToolGuardrail(config: AutoModeGuardrailConfig): AutoModeToolGuardrail;
672
838
 
673
- export { recordBlock as $, CONSECUTIVE_THRESHOLD as C, ERROR_THRESHOLD as E, checkAbsoluteDeny as I, collectAllSignals as J, computeRulesFingerprint as M, createAutoModeToolGuardrail as N, createCircuitBreaker as O, createDenialTracker as P, formatAgentsForPrompt as Q, getKodaxGlobalDir as U, loadAgentsFiles as V, WINDOW_MS as W, loadAutoRules as X, parseAutoRules as Y, readTrustState as Z, recordAllow as _, recordError as a0, shouldFallback$1 as a1, shouldFallback as a2, trustProjectRules as a3, CUMULATIVE_THRESHOLD as u };
674
- export type { AbsoluteDenyCheck as A, RulesLoadResult as B, DenialTracker as D, SkippedRulesSource as F, ToolCallSignal as G, TrustState as H, KodaXMcpConnectMode as K, LoadAgentsOptions as L, RulesLoadError as R, SignalCollector as S, TierZeroPatternId as T, AbsoluteDenyMatch as a, AbsoluteDenyMiss as b, AbsoluteDenyResult as c, AgentsFile as d, AutoModeAskUser as e, AutoModeAskUserVerdict as f, AutoModeCallAnalyzer as g, AutoModeEngine as h, AutoModeGuardrailConfig as i, AutoModePermissionBoundary as j, AutoModePermissionOperation as k, AutoModePermissionReview as l, AutoModePermissionTarget as m, AutoModeRulesContext as n, AutoModeRulesDecision as o, AutoModeRulesEvaluator as p, AutoModeSharedState as q, AutoModeStats as r, AutoModeToolGuardrail as s, AutoRules as t, CircuitBreaker as v, KodaXMcpServerConfig as w, KodaXMcpServersConfig as x, KodaXMcpTransport as y, LoadedRulesSource as z };
839
+ export { createAutoModeToolGuardrail as $, CONSECUTIVE_THRESHOLD as C, DEFAULT_CLASSIFIER_TIMEOUT_MS as F, ERROR_THRESHOLD as H, WINDOW_MS as W, checkAbsoluteDeny as X, classify as Y, collectAllSignals as Z, computeRulesFingerprint as _, createCircuitBreaker as a0, createDenialTracker as a1, formatAgentsForPrompt as a2, getKodaxGlobalDir as a3, loadAgentsFiles as a4, loadAutoRules as a5, parseAutoRules as a6, readTrustState as a7, recordAllow as a8, recordBlock as a9, recordError as aa, shouldFallback$1 as ab, shouldFallback as ac, trustProjectRules as ad, CUMULATIVE_THRESHOLD as v };
840
+ export type { AbsoluteDenyCheck as A, ClassifierToolProjectionResolver as B, ClassifyDecision as D, ClassifyOptions as E, DenialTracker as G, KodaXMcpServerConfig as I, KodaXMcpServersConfig as J, KodaXMcpConnectMode as K, KodaXMcpTransport as L, LoadAgentsOptions as M, LoadedRulesSource as N, RulesLoadResult as O, PermissionIntentEvidence as P, SkippedRulesSource as Q, RulesLoadError as R, SignalCollector as S, TierZeroPatternId as T, ToolCallSignal as U, TrustState as V, AbsoluteDenyMatch as a, AbsoluteDenyMiss as b, AbsoluteDenyResult as c, AgentsFile as d, AutoModeAskUser as e, AutoModeAskUserVerdict as f, AutoModeCallAnalyzer as g, AutoModeDecisionDiagnostics as h, AutoModeEngine as i, AutoModeGuardrailConfig as j, AutoModePermissionBoundary as k, AutoModePermissionOperation as l, AutoModePermissionReview as m, AutoModePermissionTarget as n, AutoModeRulesContext as o, AutoModeRulesDecision as p, AutoModeRulesEvaluator as q, AutoModeSharedState as r, AutoModeStats as s, AutoModeToolGuardrail as t, AutoRules as u, CircuitBreaker as w, ClassifierAttemptDiagnostics as x, ClassifierAttemptOutcome as y, ClassifierFailureKind as z };
@@ -1,5 +1,5 @@
1
1
  import { k as KodaXMessage } from './types.d-DIpZJKUl.js';
2
- import { bM as KodaXSessionLineage } from './types.d-RdWRfUEs.js';
2
+ import { bU as KodaXSessionLineage } from './types.d-BA-Jwpfs.js';
3
3
 
4
4
  type KodaXSessionHistoryScope = 'compacted' | 'all';
5
5
  type KodaXSessionHistorySource = 'user' | 'assistant' | 'system' | 'tool' | 'child_task';