@scotthuang/agent-knock-knock 0.12.15 → 0.12.16

package/dist/src/host-profile-cli-adapter.d.ts

@@ -0,0 +1,8 @@
+export interface HostProfileCliOptions extends Record<string, unknown> {
+    action?: unknown;
+    profile?: unknown;
+    host?: unknown;
+    hostVersion?: unknown;
+}
+export declare function runHostProfileCommand(options: HostProfileCliOptions): void;
+export declare function runHostProfileDoctor(options: HostProfileCliOptions): void;

package/dist/src/host-profile-cli-adapter.js

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import { assertHostProfileCompatibility, assertHostProfileCallbackExecutableReady, hostProfileControllerScope, resolveHostProfileControllerContext } from "./host-profile.js";
+import { cliCwd, cliEnv, setCliExitCode, writeCliStdout } from "./cli-runtime-context.js";
+import { writeCliJson } from "./cli-command-runtime.js";
+import { defaultHostProfileRegistry, selectHostProfileV1 } from "./host-profile-runtime.js";
+const HOST_PROFILE_STARTER_URL = new URL("../../examples/host-profiles/command-json-starter.json", import.meta.url);
+export function runHostProfileCommand(options) {
+    const action = requiredString(options.action, "host-profile action");
+    if (action === "example") {
+        if (options.profile !== undefined) {
+            throw new Error("host-profile example does not accept a Profile path");
+        }
+        writeCliStdout(fs.readFileSync(HOST_PROFILE_STARTER_URL, "utf8"));
+        return;
+    }
+    if (action === "list") {
+        if (options.profile !== undefined) {
+            throw new Error("host-profile list does not accept a Profile path");
+        }
+        writeCliJson({
+            schema: "agent-knock-knock/host-profile-list",
+            version: 1,
+            profiles: defaultHostProfileRegistry.list()
+        });
+        return;
+    }
+    if (action !== "validate") {
+        throw new Error("host-profile action must be example, list, or validate");
+    }
+    const selected = selectHostProfileV1(requiredString(options.profile, "host-profile validate path or built-in id"), { cwd: cliCwd(), registry: defaultHostProfileRegistry });
+    const compatibility = optionalCompatibility(options);
+    if (compatibility) {
+        assertHostProfileCompatibility(selected.profile, compatibility);
+    }
+    const controllerScope = hostProfileControllerScope(selected.profile);
+    writeCliJson({
+        ok: true,
+        schema: selected.profile.schema,
+        version: selected.profile.version,
+        source: selected.source,
+        selection: selected.selection,
+        id: selected.profile.id,
+        revision: selected.profile.revision,
+        fingerprint: selected.fingerprint,
+        compatibility: selected.profile.compatibility,
+        compatibility_checked: compatibility !== undefined,
+        controller_context_driver: selected.profile.controllerContext.driver,
+        controller_context_scope: controllerScope,
+        standalone_bridge_compatible: controllerScope === "startup_v1",
+        callback_driver: selected.profile.callback.driver
+    });
+}
+export function runHostProfileDoctor(options) {
+    const checks = [];
+    let selected;
+    try {
+        selected = selectHostProfileV1(requiredString(options.profile, "--host-profile"), { cwd: cliCwd(), registry: defaultHostProfileRegistry });
+        checks.push({ name: "profile", status: "ok" });
+    }
+    catch (error) {
+        checks.push({
+            name: "profile",
+            status: "error",
+            detail: errorMessage(error)
+        });
+        finishDoctor(checks);
+        return;
+    }
+    const controllerScope = hostProfileControllerScope(selected.profile);
+    if (controllerScope === "route_bound_v1") {
+        checks.push({
+            name: "standalone_bridge_scope",
+            status: "error",
+            scope: controllerScope,
+            detail: "route_bound_v1 is for a Host-native connector and is not supported " +
+                "by the standalone Host Bridge"
+        });
+    }
+    try {
+        const compatibility = requiredCompatibility(options);
+        assertHostProfileCompatibility(selected.profile, compatibility);
+        checks.push({
+            name: "host_compatibility",
+            status: "ok",
+            host: compatibility.host,
+            version: compatibility.version,
+            range: selected.profile.compatibility.range
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: "host_compatibility",
+            status: "error",
+            detail: errorMessage(error)
+        });
+    }
+    try {
+        resolveHostProfileControllerContext(selected.profile, cliEnv());
+        checks.push({
+            name: "controller_context",
+            status: "ok",
+            variable: selected.profile.controllerContext.sessionIdVariable
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: "controller_context",
+            status: "error",
+            variable: selected.profile.controllerContext.sessionIdVariable,
+            detail: errorMessage(error)
+        });
+    }
+    try {
+        assertHostProfileCallbackExecutableReady(selected.profile.callback.executable, selected.profile.callback.environment.allow);
+        checks.push({
+            name: "callback_executable",
+            status: "ok",
+            path: selected.profile.callback.executable
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: "callback_executable",
+            status: "error",
+            path: selected.profile.callback.executable,
+            detail: errorMessage(error)
+        });
+    }
+    finishDoctor(checks, {
+        profile_id: selected.profile.id,
+        profile_revision: selected.profile.revision,
+        profile_fingerprint: selected.fingerprint,
+        controller_context_scope: controllerScope,
+        standalone_bridge_compatible: controllerScope === "startup_v1"
+    });
+}
+function finishDoctor(checks, detail = {}) {
+    const ok = checks.every((check) => check.status === "ok");
+    writeCliJson({
+        ok,
+        mode: "host_bridge",
+        ...detail,
+        checks
+    });
+    if (!ok)
+        setCliExitCode(1);
+}
+function optionalCompatibility(options) {
+    if (options.host === undefined && options.hostVersion === undefined) {
+        return undefined;
+    }
+    return requiredCompatibility(options);
+}
+function requiredCompatibility(options) {
+    return {
+        host: requiredString(options.host, "--host"),
+        version: requiredString(options.hostVersion, "--host-version")
+    };
+}
+function requiredString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${label} is required`);
+    }
+    return value;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=host-profile-cli-adapter.js.map

package/dist/src/host-profile-cli-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-profile-cli-adapter.js","sourceRoot":"","sources":["../../src/host-profile-cli-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,EACL,8BAA8B,EAC9B,wCAAwC,EACxC,0BAA0B,EAC1B,mCAAmC,EACpC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,MAAM,EACN,MAAM,EACN,cAAc,EACd,cAAc,EACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACpB,MAAM,2BAA2B,CAAC;AASnC,MAAM,wBAAwB,GAAG,IAAI,GAAG,CACtC,wDAAwD,EACxD,OAAO,IAAI,CAAC,GAAG,CAChB,CAAC;AAEF,MAAM,UAAU,qBAAqB,CACnC,OAA8B;IAE9B,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IACrE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACzE,CAAC;QACD,cAAc,CAAC,EAAE,CAAC,YAAY,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAAC,CAAC;QAClE,OAAO;IACT,CAAC;IACD,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACtE,CAAC;QACD,YAAY,CAAC;YACX,MAAM,EAAE,qCAAqC;YAC7C,OAAO,EAAE,CAAC;YACV,QAAQ,EAAE,0BAA0B,CAAC,IAAI,EAAE;SAC5C,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IACD,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,QAAQ,GAAG,mBAAmB,CAClC,cAAc,CAAC,OAAO,CAAC,OAAO,EAAE,2CAA2C,CAAC,EAC5E,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,0BAA0B,EAAE,CACxD,CAAC;IACF,MAAM,aAAa,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,aAAa,EAAE,CAAC;QAClB,8BAA8B,CAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IAClE,CAAC;IACD,MAAM,eAAe,GAAG,0BAA0B,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACrE,YAAY,CAAC;QACX,EAAE,EAAE,IAAI;QACR,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM;QAC/B,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,OAAO;QACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,EAAE;QACvB,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ;QACnC,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,aAAa,EAAE,QAAQ,CAAC,OAAO,CAAC,aAAa;QAC7C,qBAAqB,EAAE,aAAa,KAAK,SAAS;QAClD,yBAAyB,EAAE,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,MAAM;QACpE,wBAAwB,EAAE,eAAe;QACzC,4BAA4B,EAAE,eAAe,KAAK,YAAY;QAC9D,eAAe,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM;KAClD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAA8B;IACjE,MAAM,MAAM,GAAmC,EAAE,CAAC;IAClD,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG,mBAAmB,CAC5B,cAAc,CAAC,OAAO,CAAC,OAAO,EAAE,gBAAgB,CAAC,EACjD,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,0BAA0B,EAAE,CACxD,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,OAAO;YACf,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC;SAC5B,CAAC,CAAC;QACH,YAAY,CAAC,MAAM,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,eAAe,GAAG,0BAA0B,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACrE,IAAI,eAAe,KAAK,gBAAgB,EAAE,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,yBAAyB;YAC/B,MAAM,EAAE,OAAO;YACf,KAAK,EAAE,eAAe;YACtB,MAAM,EACJ,qEAAqE;gBACrE,+BAA+B;SAClC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;QACrD,8BAA8B,CAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAChE,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,oBAAoB;YAC1B,MAAM,EAAE,IAAI;YACZ,IAAI,EAAE,aAAa,CAAC,IAAI;YACxB,OAAO,EAAE,aAAa,CAAC,OAAO;YAC9B,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK;SAC5C,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,oBAAoB;YAC1B,MAAM,EAAE,OAAO;YACf,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC;QACH,mCAAmC,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAChE,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,oBAAoB;YAC1B,MAAM,EAAE,IAAI;YACZ,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,iBAAiB;SAC/D,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,oBAAoB;YAC1B,MAAM,EAAE,OAAO;YACf,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,iBAAiB;YAC9D,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC;QACH,wCAAwC,CACtC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,EACpC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAC5C,CAAC;QACF,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,qBAAqB;YAC3B,MAAM,EAAE,IAAI;YACZ,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU;SAC3C,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,qBAAqB;YAC3B,MAAM,EAAE,OAAO;YACf,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU;YAC1C,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,YAAY,CAAC,MAAM,EAAE;QACnB,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC,EAAE;QAC/B,gBAAgB,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ;QAC3C,mBAAmB,EAAE,QAAQ,CAAC,WAAW;QACzC,wBAAwB,EAAE,eAAe;QACzC,4BAA4B,EAAE,eAAe,KAAK,YAAY;KAC/D,CAAC,CAAC;AACL,CAAC;AAED,SAAS,YAAY,CACnB,MAAsC,EACtC,MAAM,GAA4B,EAAE;IAEpC,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC;IAC1D,YAAY,CAAC;QACX,EAAE;QACF,IAAI,EAAE,aAAa;QACnB,GAAG,MAAM;QACT,MAAM;KACP,CAAC,CAAC;IACH,IAAI,CAAC,EAAE;QAAE,cAAc,CAAC,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,qBAAqB,CAC5B,OAA8B;IAE9B,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,qBAAqB,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,qBAAqB,CAC5B,OAA8B;IAE9B,OAAO;QACL,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;QAC5C,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,gBAAgB,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,KAAc,EAAE,KAAa;IACnD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,cAAc,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}

package/dist/src/host-profile-runtime.d.ts

@@ -0,0 +1,55 @@
+import { type HostProfileControllerScopeV1, type HostProfileRegistry, type HostProfileV1 } from "./host-profile.js";
+import { type CallbackRouteV1 } from "./callback-transport.js";
+export declare const AKK_HOST_PROFILE_SELECTION: "AKK_HOST_PROFILE_SELECTION";
+export declare const AKK_HOST_PROFILE_SOURCE: "AKK_HOST_PROFILE_SOURCE";
+export declare const AKK_HOST_PROFILE_FINGERPRINT: "AKK_HOST_PROFILE_FINGERPRINT";
+export declare const AKK_HOST_PROFILE_HOST: "AKK_HOST_PROFILE_HOST";
+export declare const AKK_HOST_PROFILE_HOST_VERSION: "AKK_HOST_PROFILE_HOST_VERSION";
+export declare const defaultHostProfileRegistry: HostProfileRegistry;
+export interface SelectedHostProfileV1 {
+    readonly source: "built_in" | "file";
+    readonly selection: string;
+    readonly fingerprint: string;
+    readonly profile: HostProfileV1;
+}
+export interface TrustedHostProfileRuntimeV1 {
+    readonly selected: SelectedHostProfileV1;
+    readonly controllerScope: HostProfileControllerScopeV1;
+    readonly controllerSessionId: string;
+    readonly host: string;
+    readonly hostVersion: string;
+    readonly callbackRoute: CallbackRouteV1;
+}
+export interface SelectHostProfileOptions {
+    readonly cwd?: string;
+    readonly registry?: HostProfileRegistry;
+}
+export interface CreateTrustedHostProfileRuntimeOptions extends SelectHostProfileOptions {
+    readonly selection: string;
+    readonly host: string;
+    readonly hostVersion: string;
+    readonly environment: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Resolve one startup-selected Profile. A registry id wins over filesystem
+ * interpretation so an explicit user file cannot shadow a bundled Profile.
+ */
+export declare function selectHostProfileV1(selection: string, options?: SelectHostProfileOptions): SelectedHostProfileV1;
+/** Capture all authority needed by a Host-launched Bridge at startup. */
+export declare function createTrustedHostProfileRuntime(options: CreateTrustedHostProfileRuntimeOptions): TrustedHostProfileRuntimeV1;
+/**
+ * Build the private child-process environment used by the Bridge. The exact
+ * Profile fingerprint and route-creation controller identity are captured
+ * once; model-facing tool arguments have no route/profile fields and cannot
+ * override them. A route-bound callback later uses only that persisted route.
+ */
+export declare function hostProfileRelayEnvironment(runtime: TrustedHostProfileRuntimeV1, baseEnvironment: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv;
+/**
+ * Re-resolve trusted Bridge authority inside a CLI/monitor child. User Profile
+ * edits after Bridge startup fail closed unless their complete fingerprint is
+ * unchanged.
+ */
+export declare function trustedHostProfileRuntimeFromEnvironment(environment: Readonly<NodeJS.ProcessEnv>, options?: SelectHostProfileOptions): TrustedHostProfileRuntimeV1 | undefined;
+/** Add only trusted in-process route fields needed by new Turn/Watch creation. */
+export declare function applyTrustedHostProfileCliOptions(commandName: string | undefined, options: Readonly<Record<string, unknown>>, environment: Readonly<NodeJS.ProcessEnv>, cwd: string): Record<string, unknown>;
+export declare function callbackRouteForHostProfile(profile: HostProfileV1, controllerSessionId: string): CallbackRouteV1;

package/dist/src/host-profile-runtime.js

@@ -0,0 +1,152 @@
+import { assertHostProfileCompatibility, createHostProfileRegistry, hostProfileControllerScope, hostProfileFingerprint, HOST_PROFILE_PRIVATE_ENVIRONMENT_VARIABLES, loadHostProfileV1, resolveHostProfileControllerContext } from "./host-profile.js";
+import { CALLBACK_ROUTE_SCHEMA, CALLBACK_ROUTE_VERSION } from "./callback-transport.js";
+export const AKK_HOST_PROFILE_SELECTION = HOST_PROFILE_PRIVATE_ENVIRONMENT_VARIABLES[0];
+export const AKK_HOST_PROFILE_SOURCE = HOST_PROFILE_PRIVATE_ENVIRONMENT_VARIABLES[1];
+export const AKK_HOST_PROFILE_FINGERPRINT = HOST_PROFILE_PRIVATE_ENVIRONMENT_VARIABLES[2];
+export const AKK_HOST_PROFILE_HOST = HOST_PROFILE_PRIVATE_ENVIRONMENT_VARIABLES[3];
+export const AKK_HOST_PROFILE_HOST_VERSION = HOST_PROFILE_PRIVATE_ENVIRONMENT_VARIABLES[4];
+export const defaultHostProfileRegistry = createHostProfileRegistry();
+/**
+ * Resolve one startup-selected Profile. A registry id wins over filesystem
+ * interpretation so an explicit user file cannot shadow a bundled Profile.
+ */
+export function selectHostProfileV1(selection, options = {}) {
+    const requested = requiredCleanString(selection, "host profile selection");
+    const registry = options.registry ?? defaultHostProfileRegistry;
+    const builtIn = registry.resolve(requested);
+    if (builtIn) {
+        return Object.freeze({
+            source: "built_in",
+            selection: builtIn.id,
+            fingerprint: hostProfileFingerprint(builtIn),
+            profile: builtIn
+        });
+    }
+    const loaded = loadHostProfileV1(requested, {
+        cwd: options.cwd,
+        registry
+    });
+    return Object.freeze({
+        source: "file",
+        selection: loaded.path,
+        fingerprint: loaded.fingerprint,
+        profile: loaded.profile
+    });
+}
+/** Capture all authority needed by a Host-launched Bridge at startup. */
+export function createTrustedHostProfileRuntime(options) {
+    const selected = selectHostProfileV1(options.selection, options);
+    const host = requiredCleanString(options.host, "controller Host id");
+    const hostVersion = requiredCleanString(options.hostVersion, "controller Host version");
+    assertHostProfileCompatibility(selected.profile, {
+        host,
+        version: hostVersion
+    });
+    const context = resolveHostProfileControllerContext(selected.profile, options.environment);
+    return Object.freeze({
+        selected,
+        controllerScope: hostProfileControllerScope(selected.profile),
+        controllerSessionId: context.controllerSessionId,
+        host,
+        hostVersion,
+        callbackRoute: callbackRouteForHostProfile(selected.profile, context.controllerSessionId)
+    });
+}
+/**
+ * Build the private child-process environment used by the Bridge. The exact
+ * Profile fingerprint and route-creation controller identity are captured
+ * once; model-facing tool arguments have no route/profile fields and cannot
+ * override them. A route-bound callback later uses only that persisted route.
+ */
+export function hostProfileRelayEnvironment(runtime, baseEnvironment) {
+    return {
+        ...baseEnvironment,
+        [AKK_HOST_PROFILE_SELECTION]: runtime.selected.selection,
+        [AKK_HOST_PROFILE_SOURCE]: runtime.selected.source,
+        [AKK_HOST_PROFILE_FINGERPRINT]: runtime.selected.fingerprint,
+        [AKK_HOST_PROFILE_HOST]: runtime.host,
+        [AKK_HOST_PROFILE_HOST_VERSION]: runtime.hostVersion,
+        [runtime.selected.profile.controllerContext.sessionIdVariable]: runtime.controllerSessionId
+    };
+}
+/**
+ * Re-resolve trusted Bridge authority inside a CLI/monitor child. User Profile
+ * edits after Bridge startup fail closed unless their complete fingerprint is
+ * unchanged.
+ */
+export function trustedHostProfileRuntimeFromEnvironment(environment, options = {}) {
+    const selection = environment[AKK_HOST_PROFILE_SELECTION];
+    const markerValues = [
+        environment[AKK_HOST_PROFILE_SOURCE],
+        environment[AKK_HOST_PROFILE_FINGERPRINT],
+        environment[AKK_HOST_PROFILE_HOST],
+        environment[AKK_HOST_PROFILE_HOST_VERSION]
+    ];
+    if (selection === undefined && markerValues.every((value) => value === undefined)) {
+        return undefined;
+    }
+    if (selection === undefined || markerValues.some((value) => value === undefined)) {
+        throw new Error("trusted Host Profile runtime environment is incomplete");
+    }
+    const runtime = createTrustedHostProfileRuntime({
+        selection,
+        host: environment[AKK_HOST_PROFILE_HOST],
+        hostVersion: environment[AKK_HOST_PROFILE_HOST_VERSION],
+        environment,
+        ...options
+    });
+    if (runtime.selected.source !== environment[AKK_HOST_PROFILE_SOURCE]) {
+        throw new Error("trusted Host Profile source changed after Bridge startup");
+    }
+    if (runtime.selected.fingerprint !== environment[AKK_HOST_PROFILE_FINGERPRINT]) {
+        throw new Error("trusted Host Profile changed after Bridge startup; restart the Host Bridge");
+    }
+    return runtime;
+}
+/** Add only trusted in-process route fields needed by new Turn/Watch creation. */
+export function applyTrustedHostProfileCliOptions(commandName, options, environment, cwd) {
+    const runtime = trustedHostProfileRuntimeFromEnvironment(environment, { cwd });
+    if (!runtime)
+        return options;
+    const createsManagedTurn = commandName === "delegate" ||
+        (commandName === "send" && !nonBlankString(options.turn));
+    const ownsTerminalWatchRoute = commandName === "watch-terminal" ||
+        commandName === "reconcile-watches";
+    if (!createsManagedTurn && !ownsTerminalWatchRoute) {
+        return options;
+    }
+    return {
+        ...options,
+        callbackRoute: runtime.callbackRoute,
+        callbackRouteControllerScope: runtime.controllerScope,
+        openclawSession: runtime.controllerSessionId,
+        gatewaySession: runtime.controllerSessionId,
+        openclawBin: "agent-knock-knock-host-bridge"
+    };
+}
+export function callbackRouteForHostProfile(profile, controllerSessionId) {
+    return Object.freeze({
+        schema: CALLBACK_ROUTE_SCHEMA,
+        version: CALLBACK_ROUTE_VERSION,
+        transport: profile.callback.driver,
+        profile_id: profile.id,
+        profile_revision: profile.revision,
+        controller_session_id: requiredCleanString(controllerSessionId, "controller session id"),
+        capabilities: Object.freeze({ wake: true, respond: true })
+    });
+}
+function requiredCleanString(value, label) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.trim() !== value ||
+        /[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new Error(`${label} is missing or invalid`);
+    }
+    return value;
+}
+function nonBlankString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value
+        : undefined;
+}
+//# sourceMappingURL=host-profile-runtime.js.map

package/dist/src/host-profile-runtime.js.map

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

package/dist/src/host-profile.d.ts

@@ -0,0 +1,121 @@
+export declare const HOST_PROFILE_SCHEMA = "agent-knock-knock/host-profile";
+export declare const HOST_PROFILE_VERSION: 1;
+export declare const HOST_PROFILE_JSON_SCHEMA: string;
+export declare const HOST_PROFILE_BUILTIN_ID_PREFIX = "builtin-";
+export declare const HOST_PROFILE_MAX_FILE_BYTES: number;
+export declare const HOST_PROFILE_MAX_TIMEOUT_MS = 30000;
+export declare const HOST_PROFILE_MAX_OUTPUT_BYTES: number;
+export declare const HOST_PROFILE_PRIVATE_ENVIRONMENT_VARIABLES: readonly ["AKK_HOST_PROFILE_SELECTION", "AKK_HOST_PROFILE_SOURCE", "AKK_HOST_PROFILE_FINGERPRINT", "AKK_HOST_PROFILE_HOST", "AKK_HOST_PROFILE_HOST_VERSION"];
+export declare const HOST_PROFILE_PLACEHOLDERS: readonly ["controller.session_id", "envelope.delivery_id", "envelope.idempotency_key", "envelope.message_id", "envelope.body"];
+export type HostProfilePlaceholder = (typeof HOST_PROFILE_PLACEHOLDERS)[number];
+export type HostProfileAcknowledgementDispositionV1 = "accepted" | "retryable_failure" | "permanent_failure" | "uncertain";
+export type HostProfileControllerScopeV1 = "startup_v1" | "route_bound_v1";
+export interface HostProfileCompatibilityV1 {
+    readonly host: string;
+    readonly range: string;
+}
+export interface HostProfileEnvironmentControllerContextV1 {
+    readonly driver: "environment_v1";
+    readonly sessionIdVariable: string;
+    /**
+     * Omitted is the original v1 behavior and is equivalent to startup_v1.
+     * Keeping it omitted in the parsed model preserves existing fingerprints.
+     */
+    readonly scope?: HostProfileControllerScopeV1;
+}
+export interface HostProfileCallbackEnvironmentV1 {
+    readonly allow: readonly string[];
+}
+export interface HostProfileJsonPointerV1 {
+    readonly jsonPointer: string;
+}
+export interface HostProfileDispositionAcknowledgementV1 {
+    readonly jsonPointer: string;
+    readonly mapping: Readonly<Record<string, HostProfileAcknowledgementDispositionV1>>;
+}
+export interface HostProfileAcknowledgementV1 {
+    readonly disposition: HostProfileDispositionAcknowledgementV1;
+    readonly acceptanceId: HostProfileJsonPointerV1;
+    readonly acknowledgedDeliveryId: HostProfileJsonPointerV1;
+    readonly acknowledgedMessageId: HostProfileJsonPointerV1;
+}
+export interface HostProfileCommandJsonCallbackV1 {
+    readonly driver: "command_json_v1";
+    readonly executable: string;
+    readonly arguments: readonly string[];
+    readonly stdin: "${envelope.body}";
+    readonly environment: HostProfileCallbackEnvironmentV1;
+    readonly timeoutMs: number;
+    readonly maxOutputBytes: number;
+    readonly acknowledgement: HostProfileAcknowledgementV1;
+}
+export interface HostProfileV1 {
+    readonly $schema: typeof HOST_PROFILE_JSON_SCHEMA;
+    readonly schema: typeof HOST_PROFILE_SCHEMA;
+    readonly version: typeof HOST_PROFILE_VERSION;
+    readonly id: string;
+    readonly revision: string;
+    readonly compatibility: HostProfileCompatibilityV1;
+    readonly controllerContext: HostProfileEnvironmentControllerContextV1;
+    readonly callback: HostProfileCommandJsonCallbackV1;
+}
+export interface ParseHostProfileOptions {
+    /** Built-ins alone may use the reserved built-in id namespace. */
+    source?: "user" | "built_in";
+    /** Exact ids already owned by a built-in registry. */
+    reservedIds?: Iterable<string>;
+}
+export interface LoadedHostProfileV1 {
+    readonly source: "file";
+    readonly path: string;
+    readonly fingerprint: string;
+    readonly profile: HostProfileV1;
+}
+export interface HostProfileRegistryEntryV1 {
+    readonly source: "built_in";
+    readonly id: string;
+    readonly revision: string;
+    readonly fingerprint: string;
+    readonly compatibility: HostProfileCompatibilityV1;
+}
+export interface HostProfileRegistry {
+    list(): readonly HostProfileRegistryEntryV1[];
+    resolve(id: string): HostProfileV1 | undefined;
+    isReserved(id: string): boolean;
+}
+export interface LoadHostProfileOptions {
+    cwd?: string;
+    registry?: HostProfileRegistry;
+}
+export interface ResolvedHostProfileControllerContextV1 {
+    readonly driver: "environment_v1";
+    readonly variable: string;
+    readonly controllerSessionId: string;
+}
+export interface HostProfileCompatibilityInputV1 {
+    readonly host: string;
+    readonly version: string;
+}
+/**
+ * Parse one untrusted Profile document into a deeply immutable v1 model.
+ *
+ * Runtime validation is deliberately implemented here instead of delegated to
+ * a JSON Schema package. The published schema is documentation and tooling;
+ * this parser remains the fail-closed authority used by AKK.
+ */
+export declare function parseHostProfileV1(value: unknown, options?: ParseHostProfileOptions): HostProfileV1;
+/** Verify the configured callback path and its symlink target at Host startup. */
+export declare function assertHostProfileCallbackExecutableReady(executable: string, environmentVariables?: readonly string[]): void;
+export declare function hostProfileFingerprint(profile: HostProfileV1): string;
+/** Create the immutable built-in Profile lookup used by later Bridge wiring. */
+export declare function createHostProfileRegistry(builtInProfiles?: readonly unknown[]): HostProfileRegistry;
+/** Load one explicit JSON file; no search path or implicit Profile selection. */
+export declare function loadHostProfileV1(profilePath: string, options?: LoadHostProfileOptions): LoadedHostProfileV1;
+/** Resolve trusted controller identity only from the Host-supplied environment. */
+export declare function resolveHostProfileControllerContext(profile: HostProfileV1, environment: Readonly<Record<string, string | undefined>>): ResolvedHostProfileControllerContextV1;
+/** Return whether one exact Host identity satisfies the Profile's AND range. */
+export declare function hostProfileSupportsHostVersion(profile: HostProfileV1, input: HostProfileCompatibilityInputV1): boolean;
+/** Assert compatibility before a Bridge is allowed to use a Profile. */
+export declare function assertHostProfileCompatibility(profile: HostProfileV1, input: HostProfileCompatibilityInputV1): void;
+/** Normalize the optional scope without changing legacy Profile fingerprints. */
+export declare function hostProfileControllerScope(profile: HostProfileV1): HostProfileControllerScopeV1;