@vincemakes/kiso-core 0.1.3 → 0.1.5

package/dist/kernel/loop.d.ts

@@ -28,6 +28,7 @@
  */
 import { type Adapter, type AbortSignalLike } from "../protocol/adapter.js";
 import type { Event, StructuredError } from "../protocol/events.js";
+import type { ApprovalPolicy } from "../protocol/extension.js";
 import { EventLog } from "./event-log.js";
 import type { EventInput } from "./event-log.js";
 import type { AssistantBlock, AssistantMessage, Message, ToolResultMessage } from "../protocol/messages.js";
@@ -95,6 +96,19 @@ export interface LoopConfig {
     readonly resolveUncertainty?: (executionId: string) => Promise<"rerun" | "abandoned">;
     /** 第四轮(对抗): the uncertainty twin of `approvalVerdict`. */
     readonly uncertaintyVerdict?: (executionId: string) => "rerun" | "abandoned" | undefined;
+    /**
+     * E1: extension approval policies, tagged by their owning extension —
+     * decided BEFORE the human flow. Any deny wins (the FIRST denial's
+     * reason); else any ask falls into the existing flow; all allow
+     * auto-approves. A policy that throws counts as ask. Allow/deny are
+     * recorded durably with decidedBy = the extension's name, never pausing
+     * for a human; a durable decision already recorded (resume) takes
+     * effect and the chain never re-runs.
+     */
+    readonly approvalPolicies?: readonly {
+        readonly extension: string;
+        readonly policy: ApprovalPolicy;
+    }[];
 }
 export declare const DEFAULT_MAX_TURNS = 10;
 export declare const DEFAULT_MAX_RETRIES = 2;

package/dist/kernel/loop.js

@@ -27,14 +27,14 @@
  * re-stream that duplicates output or tool calls.
  */
 import { isAdapterEvent } from "../protocol/adapter.js";
-import { estimateTokens, KEEP_RECENT_TURNS, microcompact } from "./compaction.js";
+import { estimateTokens, microcompact } from "./compaction.js";
 import { EventLog } from "./event-log.js";
 import { ToolRegistry } from "../tools/registry.js";
 import { validateArgs } from "../tools/validate.js";
 import { NoOpHooks } from "./hooks.js";
 import { resolveModeProfile } from "./mode.js";
 import { denialResult } from "./permission.js";
-import { messagesToEvents, projectMessages } from "./project.js";
+import { messagesToEvents, MICROCOMPACTABLE, projectMessages } from "./project.js";
 export const DEFAULT_MAX_TURNS = 10;
 export const DEFAULT_MAX_RETRIES = 2;
 export async function* loop(config) {
@@ -363,7 +363,7 @@ export async function* loop(config) {
             }
             let currentExecutionId;
             try {
-                for await (const ev of executeOne(call, registry, hooks, { signal: signal ?? NEVER_ABORT }, log, config.resolveApproval, config.approvalVerdict, signal)) {
+                for await (const ev of executeOne(call, registry, hooks, { signal: signal ?? NEVER_ABORT }, log, config.resolveApproval, config.approvalVerdict, signal, config.approvalPolicies)) {
                     // 四: the identity of THIS execution comes from the stream —
                     // a historical same-callId execution must never be mistaken
                     // for this call's (the provider callId may repeat across runs).
@@ -531,7 +531,7 @@ function terminalForStop(reason) {
  * blocks with a precondition result — the handler never auto-runs a
  * possibly-executed side effect.
  */
-async function* executeOne(call, registry, hooks, ctx, log, resolveApproval, resolveApprovalVerdict, signal) {
+async function* executeOne(call, registry, hooks, ctx, log, resolveApproval, resolveApprovalVerdict, signal, approvalPolicies) {
     const payload = {
         callId: call.callId,
         name: call.name,
@@ -588,10 +588,80 @@ async function* executeOne(call, registry, hooks, ctx, log, resolveApproval, res
     // all. Checked again here, after any permission path.
     if (signal?.aborted)
         throw ABORTED;
+    // ── E1: the extension policy chain, decided BEFORE the human flow ─────
+    // A durable POLICY decision for THIS call takes effect on resume — the
+    // chain never re-runs when its verdict is already in the log (同构
+    // alreadyReplaced: the persisted fact speaks for the call). The match is
+    // the same logical call: same callId, decidedBy set (a policy verdict,
+    // never a human's), and input identical to the original tool_call_end —
+    // a re-issued call with different arguments is a NEW call and re-decided.
+    // Composition: deny > ask > allow — any deny wins (the FIRST denial's
+    // reason), else any ask falls into the existing human flow below, and
+    // only an ALL-allow chain auto-approves: recorded durably with decidedBy
+    // = the extension's name, never a human-visible pause. A policy that
+    // throws counts as ask.
+    const originalCall = [...log.all].reverse().find((e) => e.type === "tool_call_end" && e.callId === call.callId);
+    const durable = originalCall !== undefined && JSON.stringify(originalCall.input) === JSON.stringify(call.input)
+        ? log.all.find((e) => e.type === "permission_decided" && e.decidedBy !== undefined && e.callId === call.callId)
+        : undefined;
+    let chainVerdict;
+    let deniedReason;
+    let deniedBy;
+    if (durable === undefined && approvalPolicies !== undefined && approvalPolicies.length > 0) {
+        for (const { extension, policy } of approvalPolicies) {
+            let v;
+            try {
+                v = await raceAbort(Promise.resolve(policy.decide(payload, ctx)), signal);
+            }
+            catch {
+                v = { action: "ask" }; // 抛错 = 该扩展计为 ask
+            }
+            if (v.action === "deny") {
+                deniedBy ??= extension;
+                deniedReason ??= v.reason; // the FIRST denial's reason
+            }
+            else if (v.action === "ask") {
+                chainVerdict = { action: "ask" };
+            }
+        }
+        if (deniedBy !== undefined) {
+            chainVerdict = { action: "deny", reason: deniedReason ?? "denied" };
+        }
+        else if (chainVerdict === undefined) {
+            chainVerdict = { action: "allow" };
+        }
+        if (chainVerdict.action !== "ask") {
+            // allow/deny are PERSISTED FACTS (decidedBy = the extension) —
+            // never a human pause.
+            yield log.append({
+                type: "permission_decided",
+                decisionId: `d-${log.lastSeq + 1}`,
+                callId: call.callId,
+                decision: chainVerdict.action === "allow" ? "approved" : "denied",
+                ...(chainVerdict.action === "deny" ? { reason: chainVerdict.reason } : {}),
+                decidedBy: deniedBy ?? approvalPolicies[0].extension,
+            });
+        }
+    }
+    if (chainVerdict?.action === "deny") {
+        yield emitResult(denialResult(chainVerdict.reason));
+        return;
+    }
+    if (durable !== undefined && durable.decision === "denied") {
+        yield emitResult(denialResult(durable.reason ?? "denied"));
+        return;
+    }
+    if (chainVerdict?.action === "ask" && hooks.onPreTool === undefined) {
+        // No human flow exists — the ask degrades to an honest denial, never
+        // an unasked execution (mirrors the defer-without-channel path).
+        yield emitResult(denialResult("a policy asked for a human decision, but no approval flow is configured"));
+        return;
+    }
     // Permission negotiation — defer is a REAL pause (Phase D). C 组: the
     // hook itself is cancelable (a slow policy query must not outlive an
-    // abort), and the signal is re-checked after it returns.
-    if (hooks.onPreTool) {
+    // abort), and the signal is re-checked after it returns. Skipped when
+    // the policy chain already decided (durable or all-allow).
+    if (durable === undefined && chainVerdict?.action !== "allow" && hooks.onPreTool) {
         const decision = await raceAbort(hooks.onPreTool(payload, ctx), signal);
         if (signal?.aborted)
             throw ABORTED;
@@ -797,19 +867,42 @@ function sleep(ms, signal) {
     });
 }
 /**
- * C 区: the boundary seq for a microcompact — the seq of the user input
- * KEEP_RECENT_TURNS+1 places from the end (everything BEFORE that user
- * input is old enough to clear; the recent turns stay intact). Undefined
- * when the history is too short to clear anything.
+ * C 区 (自举 #3): how many of the NEWEST compactable tool results survive a
+ * microcompact boundary — the model must keep reasoning over the recent
+ * results, whatever turn they belong to.
+ */
+const KEEP_COMPACTABLE_RESULTS = 4;
+/**
+ * C 区: the boundary seq for a microcompact — drawn by COMPACTABLE-RESULT
+ * recentness, never user turns: a SINGLE user turn that reads several big
+ * files (the coding agent's main overflow shape) crosses the threshold and
+ * must trigger. The newest KEEP_COMPACTABLE_RESULTS still-visible
+ * compactable tool results stay intact; the boundary points AT the
+ * (K+1)th-newest of them, so it and everything older is cleared. Results
+ * already cleared by an earlier boundary do not count toward the kept
+ * window — each new boundary makes progress. Undefined when fewer than
+ * K+1 compactable results remain (the kept window is the whole context).
  */
 function microcompactBoundarySeq(events) {
-    const userSeqs = [];
+    const callName = new Map();
+    let lastCleared = -1;
+    for (const ev of events) {
+        if (ev.type === "tool_call_end")
+            callName.set(ev.callId, ev.name);
+        if (ev.type === "microcompacted" && ev.beforeSeq > lastCleared)
+            lastCleared = ev.beforeSeq;
+    }
+    const visible = [];
     for (const ev of events) {
-        if (ev.type === "user_input")
-            userSeqs.push(ev.seq);
+        if (ev.type !== "tool_result" || ev.seq <= lastCleared)
+            continue;
+        const name = callName.get(ev.callId);
+        if (name !== undefined && MICROCOMPACTABLE.has(name))
+            visible.push(ev.seq);
     }
-    const boundary = userSeqs[userSeqs.length - KEEP_RECENT_TURNS - 1];
-    return boundary !== undefined ? boundary - 1 : undefined;
+    if (visible.length <= KEEP_COMPACTABLE_RESULTS)
+        return undefined;
+    return visible[visible.length - KEEP_COMPACTABLE_RESULTS - 1];
 }
 /** A signal that never aborts — for executions outside any abort scope. */
 const NEVER_ABORT = {

package/dist/kernel/project.d.ts

@@ -22,6 +22,13 @@
 import type { Event } from "../protocol/events.js";
 import type { EventInput } from "./event-log.js";
 import type { AssistantBlock, Message, MessageSource } from "../protocol/messages.js";
+/**
+ * C 区: tools whose output is eligible for microcompact clearing — reads,
+ * listings, searches, and shell output. write/edit outputs are short and
+ * never cleared. Exported so the loop's boundary computation (自举 #3)
+ * counts exactly the results the projection can clear.
+ */
+export declare const MICROCOMPACTABLE: Set<string>;
 /** The tag that makes a tool result un-clearable (C 区). */
 export declare const DO_NOT_COMPACT = "do-not-compact";
 /**

package/dist/kernel/project.js

@@ -22,9 +22,10 @@
 /**
  * C 区: tools whose output is eligible for microcompact clearing — reads,
  * listings, searches, and shell output. write/edit outputs are short and
- * never cleared.
+ * never cleared. Exported so the loop's boundary computation (自举 #3)
+ * counts exactly the results the projection can clear.
  */
-const MICROCOMPACTABLE = new Set(["read_file", "list_dir", "search_text", "shell"]);
+export const MICROCOMPACTABLE = new Set(["read_file", "list_dir", "search_text", "shell"]);
 /** The tag that makes a tool result un-clearable (C 区). */
 export const DO_NOT_COMPACT = "do-not-compact";
 /**

package/dist/protocol/events.d.ts

@@ -268,6 +268,9 @@ export interface PermissionDecided {
     readonly callId?: string;
     readonly decision: "approved" | "denied";
     readonly reason?: string;
+    /** E1: the deciding extension's name — present ONLY on policy decisions;
+     *  absent = the human decided (old logs stay compatible). */
+    readonly decidedBy?: string;
 }
 /**
  * A permission request was CLOSED because its run terminated first (B 组):

package/dist/protocol/events.js

@@ -209,7 +209,8 @@ const EVENT_VALIDATORS = {
     permission_decided: (v) => typeof v.decisionId === "string" &&
         (v.decision === "approved" || v.decision === "denied") &&
         (v.callId === undefined || typeof v.callId === "string") &&
-        (v.reason === undefined || typeof v.reason === "string"),
+        (v.reason === undefined || typeof v.reason === "string") &&
+        (v.decidedBy === undefined || typeof v.decidedBy === "string"),
     permission_expired: (v) => typeof v.decisionId === "string" && typeof v.reason === "string",
     uncertain_pending: (v) => typeof v.executionId === "string" && typeof v.callId === "string" && typeof v.name === "string" && typeof v.error === "string",
     microcompacted: (v) => isNonNegativeInt(v.beforeSeq),

package/dist/protocol/extension.d.ts

@@ -0,0 +1,42 @@
+/**
+ * E1 — extension approval policies: pure types, no runtime.
+ *
+ * An extension is a named bundle of optional capabilities: hooks (composed
+ * AFTER the harness's own — 既有先行), tools (merged into the registry), and
+ * approval policies (the loop's policy chain, decided BEFORE the human
+ * flow). This file is types-only: loading and composition live in the
+ * runtime package (loadExtensions) and the kernel loop.
+ */
+import type { HookHost } from "../kernel/hooks.js";
+import type { Tool, ToolContext } from "../tools/tool.js";
+/** The call a policy decides on — the tool's name and parsed input. */
+export interface PolicyCall {
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+}
+/**
+ * A policy's verdict. `ask` defers to the existing human approval flow;
+ * `deny` carries the reason the model sees; `allow` auto-approves.
+ */
+export type PolicyVerdict = {
+    readonly action: "allow";
+} | {
+    readonly action: "deny";
+    readonly reason: string;
+} | {
+    readonly action: "ask";
+};
+/** One approval policy — a pure decide function over a tool call. */
+export interface ApprovalPolicy {
+    readonly decide: (call: PolicyCall, ctx: ToolContext) => PolicyVerdict | Promise<PolicyVerdict>;
+}
+/**
+ * A loaded extension. `name` is unique per installation (the loader rejects
+ * duplicates loudly); hooks/tools/approvals are all optional.
+ */
+export interface KisoExtension {
+    readonly name: string;
+    readonly hooks?: HookHost;
+    readonly tools?: readonly Tool[];
+    readonly approvals?: readonly ApprovalPolicy[];
+}

package/dist/protocol/extension.js

@@ -0,0 +1,10 @@
+/**
+ * E1 — extension approval policies: pure types, no runtime.
+ *
+ * An extension is a named bundle of optional capabilities: hooks (composed
+ * AFTER the harness's own — 既有先行), tools (merged into the registry), and
+ * approval policies (the loop's policy chain, decided BEFORE the human
+ * flow). This file is types-only: loading and composition live in the
+ * runtime package (loadExtensions) and the kernel loop.
+ */
+export {};

package/dist/protocol/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./events.js";
 export * from "./messages.js";
 export * from "./adapter.js";
+export * from "./extension.js";

package/dist/protocol/index.js

@@ -1,3 +1,4 @@
 export * from "./events.js";
 export * from "./messages.js";
 export * from "./adapter.js";
+export * from "./extension.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vincemakes/kiso-core",
-  "version": "0.1.3",
-  "description": "kiso(\u57fa\u790e) core \u2014 protocol, event log, loop, hooks, modes, permissions, compaction, delivery truth. The 2,000-line kernel at the bottom of the kiso framework.",
+  "version": "0.1.5",
+  "description": "kiso(基礎) core — protocol, event log, loop, hooks, modes, permissions, compaction, delivery truth. The 2,000-line kernel at the bottom of the kiso framework.",
   "type": "module",
   "license": "MIT",
   "exports": {
@@ -33,7 +33,7 @@
     "openai"
   ],
   "devDependencies": {
-    "@vincemakes/kiso-evals": "0.1.3",
+    "@vincemakes/kiso-evals": "0.1.5",
     "@types/node": "^26.1.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"