@scotthuang/agent-knock-knock 0.13.3 → 0.13.4

package/dist/src/semantic-private-authority-offers.js

@@ -0,0 +1,261 @@
+export const SEMANTIC_PRIVATE_AUTHORITY_OFFER_TTL_MS = 10 * 60 * 1000;
+export const SEMANTIC_PRIVATE_AUTHORITY_OFFER_LIMIT = 512;
+export const SEMANTIC_APPROVAL_AUTHORITY_KIND = "approval";
+export const SEMANTIC_INTERACTION_AUTHORITY_KIND = "interaction";
+export const SEMANTIC_INTERACTION_AUTHORITY_SUBJECT_KINDS = [
+    "managed_turn",
+    "terminal_watch"
+];
+const storesByApi = new WeakMap();
+export function semanticApprovalAuthorityOfferKey(sessionKey, sessionId, target) {
+    return {
+        sessionKey,
+        sessionId,
+        kind: SEMANTIC_APPROVAL_AUTHORITY_KIND,
+        target
+    };
+}
+export function semanticInteractionAuthorityOfferKey(sessionKey, sessionId, subjectKindOrTurnId, subjectIdOrInteractionId, explicitInteractionId) {
+    const legacyManagedTurn = explicitInteractionId === undefined;
+    const subjectKind = legacyManagedTurn
+        ? "managed_turn"
+        : interactionAuthoritySubjectKind(subjectKindOrTurnId);
+    const subjectId = exactNonBlank(legacyManagedTurn ? subjectKindOrTurnId : subjectIdOrInteractionId, "interaction subject id");
+    const interactionId = exactNonBlank(legacyManagedTurn ? subjectIdOrInteractionId : explicitInteractionId, "interaction id");
+    return {
+        sessionKey,
+        sessionId,
+        kind: SEMANTIC_INTERACTION_AUTHORITY_KIND,
+        target: {
+            type: "interaction_subject",
+            id: JSON.stringify([subjectKind, subjectId, interactionId])
+        }
+    };
+}
+export function semanticManagedTurnInteractionAuthorityOfferKey(sessionKey, sessionId, turnId, interactionId) {
+    return semanticInteractionAuthorityOfferKey(sessionKey, sessionId, "managed_turn", turnId, interactionId);
+}
+export function semanticTerminalWatchInteractionAuthorityOfferKey(sessionKey, sessionId, watchId, interactionId) {
+    return semanticInteractionAuthorityOfferKey(sessionKey, sessionId, "terminal_watch", watchId, interactionId);
+}
+/**
+ * Invalidates every interaction response offer previously displayed for one
+ * exact subject in one exact controller conversation. Status uses this as a
+ * refresh boundary before it publishes at most one offer from the new
+ * snapshot, so an old interaction id cannot remain actionable for the rest of
+ * its TTL after the terminal UI disappears or changes.
+ */
+export function invalidateSemanticInteractionAuthorityOffersForSubject(api, sessionKey, sessionId, subjectKind, subjectId, nowMs = Date.now()) {
+    const exactApi = assertApi(api);
+    const exactSessionKey = exactNonBlank(sessionKey, "sessionKey");
+    const exactSessionId = exactNonBlank(sessionId, "sessionId");
+    const exactSubjectKind = interactionAuthoritySubjectKind(subjectKind);
+    const exactSubjectId = exactNonBlank(subjectId, "interaction subject id");
+    assertNow(nowMs);
+    const store = storesByApi.get(exactApi);
+    if (!store)
+        return 0;
+    pruneExpiredOffers(store, nowMs);
+    let invalidated = 0;
+    for (const normalizedKey of store.entries.keys()) {
+        if (normalizedInteractionOfferMatchesSubject(normalizedKey, exactSessionKey, exactSessionId, exactSubjectKind, exactSubjectId)) {
+            store.entries.delete(normalizedKey);
+            invalidated += 1;
+        }
+    }
+    return invalidated;
+}
+export function rememberSemanticPrivateAuthorityOffer(api, key, payload, nowMs = Date.now()) {
+    const normalizedKey = privateAuthorityOfferKey(key);
+    const store = privateAuthorityOfferStore(api);
+    assertNow(nowMs);
+    pruneExpiredOffers(store, nowMs);
+    const previous = store.entries.get(normalizedKey)?.payload;
+    const authorityChanged = privateAuthorityPayloadChanged(previous, payload);
+    const merged = mergePrivateAuthorityPayload(previous, payload);
+    const invalidated = authorityChanged || (previous?.invalidated === true);
+    const storedPayload = {
+        ...merged,
+        ...(invalidated ? { invalidated: true } : {})
+    };
+    if (!invalidated)
+        delete storedPayload.invalidated;
+    store.entries.delete(normalizedKey);
+    while (store.entries.size >= SEMANTIC_PRIVATE_AUTHORITY_OFFER_LIMIT) {
+        const oldest = store.entries.keys().next().value;
+        if (typeof oldest !== "string")
+            break;
+        store.entries.delete(oldest);
+    }
+    store.entries.set(normalizedKey, {
+        expiresAtMs: nowMs + SEMANTIC_PRIVATE_AUTHORITY_OFFER_TTL_MS,
+        payload: cloneAndFreezePayload(storedPayload)
+    });
+}
+export function peekSemanticPrivateAuthorityOffer(api, key, nowMs = Date.now()) {
+    return readPrivateAuthorityOffer(api, key, false, nowMs);
+}
+export function consumeSemanticPrivateAuthorityOffer(api, key, nowMs = Date.now()) {
+    return readPrivateAuthorityOffer(api, key, true, nowMs);
+}
+function readPrivateAuthorityOffer(api, key, consume, nowMs) {
+    assertNow(nowMs);
+    const store = storesByApi.get(assertApi(api));
+    if (!store)
+        return undefined;
+    const normalizedKey = privateAuthorityOfferKey(key);
+    const offer = store.entries.get(normalizedKey);
+    if (!offer) {
+        pruneExpiredOffers(store, nowMs);
+        return undefined;
+    }
+    if (offer.expiresAtMs <= nowMs) {
+        store.entries.delete(normalizedKey);
+        pruneExpiredOffers(store, nowMs);
+        return undefined;
+    }
+    if (offer.payload.invalidated === true) {
+        if (consume)
+            store.entries.delete(normalizedKey);
+        return undefined;
+    }
+    if (consume)
+        store.entries.delete(normalizedKey);
+    return offer.payload;
+}
+function privateAuthorityOfferStore(api) {
+    const exactApi = assertApi(api);
+    const existing = storesByApi.get(exactApi);
+    if (existing)
+        return existing;
+    const created = { entries: new Map() };
+    storesByApi.set(exactApi, created);
+    return created;
+}
+function privateAuthorityOfferKey(key) {
+    const sessionKey = exactNonBlank(key?.sessionKey, "sessionKey");
+    const sessionId = exactNonBlank(key?.sessionId, "sessionId");
+    const kind = exactIdentifier(key?.kind, "kind");
+    const targetType = exactIdentifier(key?.target?.type, "target.type");
+    const targetId = exactNonBlank(key?.target?.id, "target.id");
+    return JSON.stringify([sessionKey, sessionId, kind, targetType, targetId]);
+}
+function normalizedInteractionOfferMatchesSubject(normalizedKey, sessionKey, sessionId, subjectKind, subjectId) {
+    try {
+        const key = JSON.parse(normalizedKey);
+        if (!Array.isArray(key) ||
+            key.length !== 5 ||
+            key[0] !== sessionKey ||
+            key[1] !== sessionId ||
+            key[2] !== SEMANTIC_INTERACTION_AUTHORITY_KIND ||
+            key[3] !== "interaction_subject" ||
+            typeof key[4] !== "string") {
+            return false;
+        }
+        const target = JSON.parse(key[4]);
+        return Array.isArray(target) &&
+            target.length === 3 &&
+            target[0] === subjectKind &&
+            target[1] === subjectId &&
+            typeof target[2] === "string";
+    }
+    catch {
+        return false;
+    }
+}
+function exactIdentifier(value, label) {
+    const text = exactNonBlank(value, label);
+    if (!/^[a-z][a-z0-9_.-]{0,63}$/u.test(text)) {
+        throw new Error(`private authority offer ${label} is invalid`);
+    }
+    return text;
+}
+function interactionAuthoritySubjectKind(value) {
+    if (!SEMANTIC_INTERACTION_AUTHORITY_SUBJECT_KINDS.includes(value)) {
+        throw new Error("private authority offer interaction subject kind is invalid");
+    }
+    return value;
+}
+function exactNonBlank(value, label) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.trim() !== value) {
+        throw new Error(`private authority offer ${label} must be exact and non-empty`);
+    }
+    return value;
+}
+function assertApi(api) {
+    if ((typeof api !== "object" || api === null) && typeof api !== "function") {
+        throw new Error("private authority offer api must be an object");
+    }
+    return api;
+}
+function assertNow(nowMs) {
+    if (!Number.isFinite(nowMs)) {
+        throw new Error("private authority offer clock must be finite");
+    }
+}
+function pruneExpiredOffers(store, nowMs) {
+    for (const [key, offer] of store.entries) {
+        if (offer.expiresAtMs <= nowMs)
+            store.entries.delete(key);
+    }
+}
+function cloneAndFreezePayload(payload) {
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+        throw new Error("private authority offer payload must be an object");
+    }
+    let cloned;
+    try {
+        cloned = structuredClone(payload);
+    }
+    catch {
+        throw new Error("private authority offer payload must be structured-cloneable");
+    }
+    return deepFreeze(cloned, new WeakSet());
+}
+function mergePrivateAuthorityPayload(previous, update) {
+    const definedUpdate = Object.fromEntries(Object.entries(update).filter(([, value]) => value !== undefined));
+    const previousArgs = isPlainRecord(previous?.args) ? previous.args : {};
+    const updateArgs = isPlainRecord(definedUpdate.args)
+        ? definedUpdate.args
+        : undefined;
+    return {
+        ...(previous ?? {}),
+        ...definedUpdate,
+        ...(updateArgs
+            ? { args: { ...previousArgs, ...updateArgs } }
+            : Object.keys(previousArgs).length > 0
+                ? { args: previousArgs }
+                : {})
+    };
+}
+function privateAuthorityPayloadChanged(previous, update) {
+    if (!previous)
+        return false;
+    const nextFingerprint = update.fingerprint;
+    if (nextFingerprint !== undefined &&
+        previous.fingerprint !== undefined &&
+        nextFingerprint !== previous.fingerprint) {
+        return true;
+    }
+    const previousArgs = isPlainRecord(previous.args) ? previous.args : {};
+    const updateArgs = isPlainRecord(update.args) ? update.args : undefined;
+    if (!updateArgs)
+        return false;
+    return Object.keys(previousArgs).length > 0 &&
+        JSON.stringify(previousArgs) !== JSON.stringify(updateArgs);
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepFreeze(value, seen) {
+    if (typeof value !== "object" || value === null || seen.has(value)) {
+        return value;
+    }
+    seen.add(value);
+    for (const nested of Object.values(value))
+        deepFreeze(nested, seen);
+    return Object.freeze(value);
+}
+//# sourceMappingURL=semantic-private-authority-offers.js.map

package/dist/src/semantic-private-authority-offers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-private-authority-offers.js","sourceRoot":"","sources":["../../src/semantic-private-authority-offers.ts"],"names":[],"mappings":"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"}

package/dist/src/semantic-tool-arguments.d.ts

@@ -0,0 +1,9 @@
+export declare function pushTurnTarget(args: any, params: any): void;
+export declare function authoritativeManagedId(value: any, name: any): string;
+export declare function assertExclusiveRecoveryFence(params: any): void;
+export declare function pushOptional(args: any, flag: any, value: any): void;
+export declare function numberString(value: any): string | undefined;
+export declare function requiredString(value: any, name: any): string;
+export declare function requiredControllerSessionKey(value: unknown): string;
+export declare function requiredControllerSessionId(value: unknown): string;
+export declare function requiredTerminalInteractionIdentifier(value: unknown, name: string): string;

package/dist/src/semantic-tool-arguments.js

@@ -0,0 +1,64 @@
+import { nonBlankString as stringValue } from "./value-guards.js";
+import { TERMINAL_INTERACTION_LIMITS } from "./terminal-interaction-protocol.js";
+export function pushTurnTarget(args, params) {
+    if (Object.hasOwn(params, "turn_id") && Object.hasOwn(params, "conversation_id")) {
+        throw new Error("turn-target tools accept only one of turn_id or conversation_id");
+    }
+    const turnId = stringValue(params.turn_id);
+    if (turnId) {
+        args.push("--turn", authoritativeManagedId(turnId, "turn_id"));
+        return;
+    }
+    args.push("--conversation", requiredString(params.conversation_id, "turn_id"));
+}
+export function authoritativeManagedId(value, name) {
+    const id = requiredString(value, name).trim();
+    if (/^(?:only|latest|codex|claude|(?:codex|claude):latest)$/iu.test(id) ||
+        /^@[0-9a-f]+$/iu.test(id) ||
+        /^terminal:/iu.test(id)) {
+        throw new Error(`${name} must be an authoritative managed id, not a discovery selector or terminal id`);
+    }
+    return id;
+}
+export function assertExclusiveRecoveryFence(params) {
+    const expectedMessageId = stringValue(params.expected_message_id);
+    const expectedTransitionId = stringValue(params.expected_transition_id);
+    const closeFenceCount = [expectedMessageId, expectedTransitionId]
+        .filter(Boolean).length;
+    if (closeFenceCount > 1) {
+        throw new Error("close accepts only one of expected_message_id or expected_transition_id");
+    }
+    if (stringValue(params.reason) === "superseded_by_human_context_switch" &&
+        (!stringValue(params.turn_id) || stringValue(params.conversation_id))) {
+        throw new Error("human-context handoff Close requires the exact managed turn_id");
+    }
+}
+export function pushOptional(args, flag, value) {
+    if (value !== undefined && value !== "") {
+        args.push(flag, value);
+    }
+}
+export function numberString(value) {
+    return typeof value === "number" && Number.isFinite(value) ? String(value) : undefined;
+}
+export function requiredString(value, name) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${name} is required`);
+    }
+    return value;
+}
+export function requiredControllerSessionKey(value) {
+    return requiredString(value, "Controller session identity for this confirmed action");
+}
+export function requiredControllerSessionId(value) {
+    return requiredString(value, "Controller conversation incarnation for this confirmed action");
+}
+export function requiredTerminalInteractionIdentifier(value, name) {
+    const identifier = requiredString(value, name);
+    if (identifier.length > TERMINAL_INTERACTION_LIMITS.maxIdentifierLength ||
+        !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(identifier)) {
+        throw new Error(`${name} must be an exact safe interaction identifier`);
+    }
+    return identifier;
+}
+//# sourceMappingURL=semantic-tool-arguments.js.map

package/dist/src/semantic-tool-arguments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-tool-arguments.js","sourceRoot":"","sources":["../../src/semantic-tool-arguments.ts"],"names":[],"mappings":"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"}

package/dist/src/semantic-tool-catalog.d.ts

@@ -0,0 +1,48 @@
+export interface SemanticToolControllerContext {
+    readonly sessionKey?: unknown;
+    readonly sessionId?: unknown;
+}
+export interface SemanticCommandControllerContext extends SemanticToolControllerContext {
+    readonly args?: unknown;
+}
+export interface SemanticCommandCatalogEntry {
+    readonly name: string;
+    readonly description: string;
+    readonly acceptsArgs: boolean;
+    readonly requiresAuthentication: boolean;
+    readonly progressMessage: string;
+    readonly promptGuidance: readonly string[];
+    execute(context: SemanticCommandControllerContext): Promise<unknown> | unknown;
+}
+export interface SemanticToolCatalogEntry {
+    readonly label: string;
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    execute(context: SemanticToolControllerContext, toolCallId: unknown, args: unknown, signal?: AbortSignal): Promise<unknown> | unknown;
+}
+export interface SemanticToolCatalog {
+    readonly command: SemanticCommandCatalogEntry;
+    readonly tools: readonly SemanticToolCatalogEntry[];
+}
+export interface SemanticToolCatalogRegistrar {
+    registerCommand?(command: Readonly<Record<string, unknown>>): void;
+    registerTool(factory: (context: SemanticToolControllerContext) => Readonly<Record<string, unknown>>, registration: {
+        readonly name: string;
+        readonly optional: true;
+    }): void;
+}
+export declare function beginSemanticToolCatalog(runtime: object): void;
+export declare function defineSemanticCatalogTool(runtime: object, tool: SemanticToolCatalogEntry): void;
+export declare function semanticToolLabel(name: string): string;
+export declare function finishSemanticToolCatalog(runtime: object, command: SemanticCommandCatalogEntry): SemanticToolCatalog;
+/** Adapt one catalog to a context-factory registration API such as OpenClaw. */
+export declare function registerSemanticToolCatalog(registrar: SemanticToolCatalogRegistrar, catalog: SemanticToolCatalog): void;
+/**
+ * Freeze one host-neutral semantic catalog after checking its public identity.
+ *
+ * The catalog owns tool order, metadata, schema references, and execution
+ * factories. Host-specific registration APIs adapt this value; they are not a
+ * source of tool definitions.
+ */
+export declare function defineSemanticToolCatalog(command: SemanticCommandCatalogEntry, tools: readonly SemanticToolCatalogEntry[]): SemanticToolCatalog;

package/dist/src/semantic-tool-catalog.js

@@ -0,0 +1,105 @@
+const pendingToolsByRuntime = new WeakMap();
+export function beginSemanticToolCatalog(runtime) {
+    if (pendingToolsByRuntime.has(runtime)) {
+        throw new Error("semantic tool catalog construction is already active");
+    }
+    pendingToolsByRuntime.set(runtime, []);
+}
+export function defineSemanticCatalogTool(runtime, tool) {
+    const tools = pendingToolsByRuntime.get(runtime);
+    if (!tools) {
+        throw new Error("semantic tools must be defined inside catalog construction");
+    }
+    tools.push(tool);
+}
+export function semanticToolLabel(name) {
+    const action = name.replace(/^agent_knock_knock_/u, "")
+        .split("_").filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+    return `AKK ${action || "Tool"}`;
+}
+export function finishSemanticToolCatalog(runtime, command) {
+    const tools = pendingToolsByRuntime.get(runtime);
+    if (!tools) {
+        throw new Error("semantic tool catalog construction is not active");
+    }
+    pendingToolsByRuntime.delete(runtime);
+    return defineSemanticToolCatalog(command, tools);
+}
+/** Adapt one catalog to a context-factory registration API such as OpenClaw. */
+export function registerSemanticToolCatalog(registrar, catalog) {
+    registrar.registerCommand?.({
+        name: catalog.command.name,
+        description: catalog.command.description,
+        acceptsArgs: catalog.command.acceptsArgs,
+        requireAuth: catalog.command.requiresAuthentication,
+        nativeProgressMessages: { default: catalog.command.progressMessage },
+        agentPromptGuidance: catalog.command.promptGuidance,
+        handler: async (context) => catalog.command.execute(context)
+    });
+    for (const tool of catalog.tools) {
+        registrar.registerTool((context) => ({
+            label: tool.label,
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.inputSchema,
+            execute: (toolCallId, args, signal) => tool.execute(context, toolCallId, args, signal)
+        }), { name: tool.name, optional: true });
+    }
+}
+/**
+ * Freeze one host-neutral semantic catalog after checking its public identity.
+ *
+ * The catalog owns tool order, metadata, schema references, and execution
+ * factories. Host-specific registration APIs adapt this value; they are not a
+ * source of tool definitions.
+ */
+export function defineSemanticToolCatalog(command, tools) {
+    const exactCommand = Object.freeze({
+        ...command,
+        promptGuidance: Object.freeze([...command.promptGuidance])
+    });
+    requiredString(exactCommand.name, "semantic command name");
+    requiredString(exactCommand.description, "semantic command description");
+    requiredString(exactCommand.progressMessage, "semantic command progress message");
+    if (!Array.isArray(exactCommand.promptGuidance) ||
+        exactCommand.promptGuidance.some((value) => typeof value !== "string" || value.length === 0)) {
+        throw new Error("semantic command prompt guidance is invalid");
+    }
+    if (typeof exactCommand.execute !== "function") {
+        throw new Error("semantic command execute is required");
+    }
+    const names = new Set();
+    const exactTools = tools.map((tool) => {
+        const exactTool = Object.freeze({ ...tool });
+        const name = requiredString(exactTool.name, "semantic tool name");
+        requiredString(exactTool.label, `semantic tool ${name} label`);
+        requiredString(exactTool.description, `semantic tool ${name} description`);
+        if (!isRecord(exactTool.inputSchema)) {
+            throw new Error(`semantic tool ${name} input schema is required`);
+        }
+        if (typeof exactTool.execute !== "function") {
+            throw new Error(`semantic tool ${name} execute is required`);
+        }
+        if (names.has(name)) {
+            throw new Error(`duplicate semantic tool ${name}`);
+        }
+        names.add(name);
+        return exactTool;
+    });
+    return Object.freeze({
+        command: exactCommand,
+        tools: Object.freeze(exactTools)
+    });
+}
+function requiredString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${label} is required`);
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=semantic-tool-catalog.js.map

package/dist/src/semantic-tool-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-tool-catalog.js","sourceRoot":"","sources":["../../src/semantic-tool-catalog.ts"],"names":[],"mappings":"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"}