@byokit/openclaw 0.3.6 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.5.0 (2026-10-01)
+
+- Dependency update: pins @byokit/relay 0.5.1.
+
+- FIX: Wait for approval callbacks in the bridge parking test instead of assuming the gate finishes within 50 ms.
+- FIX: Successful runs preserve complete generated text in the final callback and result instead of replacing it with a capped terminal snapshot; silent and empty replies remain empty.
+
+- Add app-supplied output schemas to host and device runs, with inferred result data, local final-answer validation and typed output failures. Subscription routes and explicit API key (billed per use) opt-in are unchanged.
+
+## 0.4.0 (2026-10-01)
+
+- Dependency update: pins @byokit/ui-core 0.6.0.
+- Dependency update: pins @byokit/reach 0.6.0.
+
+- Key readiness waits through the engine's retryable restart refusal after activation; missing keys still fail without another account.
+- API key (billed per use): `addKey` verifies and stores an explicitly entered key in a separate member-owned agent, with copying disabled and no automatic subscription fallback. `run({ auth: 'apiKey' })` selects it explicitly with separate history; key-entry labels, errors and route revision dates are included.
+- Offer subscription sign-ins, including pasted tokens and native Claude Code, by default and allow their provider plugins. API key (billed per use) routes remain app opt-in; proxies, compatibility aliases and local routes stay off.
+
 ## 0.3.6 (2026-10-01)
 
 - FIX: Live orphan gateways recover after the engine rewrites its process title. Recovery verifies the recorded launch pid and process start time with the executable and isolated store paths; ambiguous ownership preserves the saved sign-in state.

package/README.md

@@ -69,6 +69,23 @@ provider or model. If the member isn't signed in to it, the run ends `{ ok: fals
 engine is never called. Leave `model` out to keep the engine's own choice. A specific sign-in (`@profile`) can't be
 picked per run: the pinned engine may still switch to another sign-in for the same provider.
 
+
+For an owner who explicitly offers keys, `kit.addKey('ana', { authChoice: 'openai-api-key', apiKey })` returns
+`ok`, `invalid` or `not_included`. Label the option **API key (billed per use)**. Select only `routes()` rows with
+`keyEntry: true`; API rows remain `offer: false`. Each route also carries its engine `revision`, `checked` date,
+label and key error word names. Submit the input directly, clear the field afterwards, and never log or save it in
+app state. The kit never returns engine key-check errors or the key. `ui-core/kits` supplies `keyStep`/`keyView`
+for entry, checking, success and failure states, using the kit's `key.*` words.
+
+To use the saved key for one run, pass `auth: 'apiKey'`. The key lives in the member's separate
+`byokit-key-<member>` agent and workspace, with `copyToAgents: false` and only that key in its local auth order.
+Its selected model is used; omit `model` or pass that same model. Key runs have separate history. To steer or stop
+one, pass `{ auth: 'apiKey' }` to `steer` or `abort` too (the device helpers accept the same option).
+Ordinary runs never enter the key agent, even when the subscription is resting. This agent boundary is necessary
+because the engine's profile pins can rotate. The `byokit-key-` member prefix is reserved. Adding another key
+replaces the previous key; a failed replacement leaves this option unavailable. If the normal agent already has
+an API key added through pass-through calls, `addKey` returns `invalid` and leaves that key untouched.
+
 A run spec also takes `system`, `images` (`{ data, mimeType }[]`), `thinking` and `tools`, a subset of the app tools
 (`KitOptions.tools` names) this run may call; any other app tool is refused at the gate before `ToolHost.gate` sees
 it. Tool events carry the engine's call `id`, the `input` on `start` and the `output` and `error` on `end`. A run that
@@ -77,6 +94,46 @@ ends ok carries `usage` (the engine's token total for the run, and `costUsd` whe
 `openclawDevice(link).run(message, o)` takes the same options over the link, and `state()` adds the kit and engine
 versions and the providers the device's member is signed in to.
 
+For a validated JSON answer, pass a literal `schema`. The result's `data` is inferred from that schema:
+
+```ts
+import type { OpenClawKit } from '@byokit/openclaw';
+
+async function summarize(kit: OpenClawKit) {
+  const end = await kit.run({
+    member: 'umer', sessionKey: 'agent:umer:report', message: 'Summarize the work.',
+    schema: {
+      type: 'object',
+      properties: { summary: { type: 'string' }, ready: { type: 'boolean' } },
+      required: ['summary', 'ready'],
+      additionalProperties: false,
+    },
+  });
+  if (end.ok && end.data) {
+    const summary: string = end.data.summary;
+    const ready: boolean = end.data.ready;
+    // Show summary and ready in the app.
+  }
+  return end;
+}
+```
+
+`openclawDevice(link).run(message, { schema })` carries the same schema and typed result over the link.
+The pinned engine has no general schema parameter: the kit adds a JSON-only instruction to the run's
+system prompt, then parses and validates the final answer locally. Partial text events are unvalidated.
+Malformed JSON or a schema mismatch returns `{ ok: false, kind: 'output', message }`; the message never
+includes the answer. The kit sends one agent request, with no kit retries or sign-in changes. Subscription
+routes stay subscriptions; an API key (billed per use) still requires the app's explicit opt-in.
+
+The supported JSON Schema subset covers types (including nullable arrays of types), objects with
+`properties`, `required` and `additionalProperties`, arrays with one `items` schema, `enum`, `const`,
+`anyOf`, `oneOf`, `allOf`, `not`, numeric bounds, string/array/object length bounds and `uniqueItems`.
+Annotations `title`, `description`, `default`, `examples` and the draft-07 `$schema` are accepted;
+defaults are never inserted and values are never coerced. Unsupported keywords (including `$ref`,
+`format` and `pattern`), malformed schemas, schemas over 64 KiB or over 32 levels deep throw before
+any Gateway request. Use `as const` for schemas defined separately; dynamic schemas return unknown
+`data`. App-specific business checks belong in the app after validation.
+
 The same kit runs offline against the fake Gateway from `@byokit/openclaw/testing` (no engine, no network, no
 account), and lists the sign-in routes it offers:
 
@@ -120,10 +177,15 @@ route: github-copilot             subscription code
 route: github-copilot-enterprise  subscription code
 route: minimax-global-oauth       subscription code
 route: minimax-cn-oauth           subscription code
+route: anthropic-cli              subscription browser
+route: setup-token                subscription browser
 ```
 
-Every offered route is a subscription sign-in. Each `Route` carries `billing` (`subscription`, `api` or `local`), so
-an app labels any other route it shows; API-billed routes are not offered by default.
+Subscription sign-ins are offered by default. API-billed routes remain in `kit.routes()` with `offer: false`;
+apps can offer them when the app or person opts in, labelled API key (billed per use). Each `Route` carries `billing` (`subscription`, `api` or
+`local`) so the app can label what is billed. Proxy routes, compatibility aliases, local runtimes stay off. Native Claude Code sign-in is offered by default. The pinned Gateway guides only some routes; other choices need manual paste or key entry. For an opted-in route, allow its `plugin` id
+in the app configuration and pass its `choice` explicitly to `kit.signIn()`.
+Offered provider plugins are allowed by default alongside the app's plugin ids.
 
 ## API at a glance
 

package/dist/device.d.ts

@@ -1,8 +1,8 @@
 import type { DeviceLink } from '@byokit/link';
 import { type AccountView } from './words.ts';
-import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, Route, RunEnd, RunEvent, SignInView } from './types.ts';
+import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, Route, RunEnd, OutputSchema, SchemaOutput, RunEvent, SignInView } from './types.ts';
 export type { GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult } from './types.ts';
-export type { Approval, Decision, KitState, PlanWindow, Route, RunEnd, RunEvent, RunUsage, SignInView } from './types.ts';
+export type { Approval, Decision, KitState, PlanWindow, Route, RunEnd, RunEvent, RunUsage, SignInView, OutputSchema, SchemaOutput } from './types.ts';
 /** One `oc.events` frame: a member's Gateway event, typed by name, or an approval add/resolve (7.2). */
 export type OpenClawLinkEvent = {
     [E in GatewayEventName]: {
@@ -19,10 +19,16 @@ export type SessionRow = {
     sessionKey: string;
     [k: string]: unknown;
 };
+type EndFrame<T = unknown> = {
+    type: 'end';
+    end: RunEnd<T>;
+};
 /** `oc.run`'s options beside the message: the member's own session, account, and the kit's run options. */
-export type DeviceRunOptions = {
+export type DeviceRunOptions<S extends OutputSchema | undefined = OutputSchema | undefined> = {
+    schema?: S;
     sessionKey?: string;
     model?: string;
+    auth?: 'apiKey';
     system?: string;
     images?: {
         data: string;
@@ -60,12 +66,13 @@ export declare function openclawDevice(link: DeviceLink): {
     };
     signOut(p: string): Promise<void>;
     sessions(): Promise<SessionRow[]>;
-    run(message: string, o?: DeviceRunOptions): AsyncIterable<RunEvent | {
-        type: 'end';
-        end: RunEnd;
-    }>;
-    steer(k: string, t: string): Promise<void>;
-    abort(k: string): Promise<void>;
+    run<const S extends OutputSchema | undefined = undefined>(message: string, o?: DeviceRunOptions<S>): AsyncIterable<RunEvent | EndFrame<SchemaOutput<S>>>;
+    steer(k: string, t: string, o?: {
+        auth?: 'apiKey';
+    }): Promise<void>;
+    abort(k: string, o?: {
+        auth?: 'apiKey';
+    }): Promise<void>;
     approvals(): Promise<Approval[]>;
     decide(id: string, d: Decision): Promise<void>;
     events(): AsyncIterable<OpenClawLinkEvent>;

package/dist/device.js

@@ -139,8 +139,9 @@ export function openclawDevice(link) {
         run: (message, o) => {
             const inner = liveStream(() => link.stream('oc.run', { message, ...(o?.sessionKey ? { sessionKey: o.sessionKey } : {}),
                 ...(o?.model !== undefined ? { model: o.model } : {}), ...(o?.system !== undefined ? { system: o.system } : {}),
+                ...(o?.auth !== undefined ? { auth: o.auth } : {}),
                 ...(o?.images !== undefined ? { images: o.images } : {}), ...(o?.thinking !== undefined ? { thinking: o.thinking } : {}),
-                ...(o?.tools !== undefined ? { tools: o.tools } : {}) }));
+                ...(o?.tools !== undefined ? { tools: o.tools } : {}), ...(o?.schema !== undefined ? { schema: o.schema } : {}) }));
             let finished = false;
             return {
                 [Symbol.asyncIterator]() {
@@ -168,11 +169,11 @@ export function openclawDevice(link) {
                 },
             };
         },
-        steer: async (k, t) => {
-            await link.request('oc.steer', { sessionKey: k, text: t });
+        steer: async (k, t, o) => {
+            await link.request('oc.steer', { sessionKey: k, text: t, ...(o?.auth ? { auth: o.auth } : {}) });
         },
-        abort: async (k) => {
-            await link.request('oc.abort', { sessionKey: k });
+        abort: async (k, o) => {
+            await link.request('oc.abort', { sessionKey: k, ...(o?.auth ? { auth: o.auth } : {}) });
         },
         approvals: () => link.request('oc.approvals'),
         decide: async (id, d) => {

package/dist/engine.js

@@ -148,7 +148,7 @@ export class Engine {
         const pluginDir = join(this.root, 'plugin');
         mkdirSync(pluginDir, { recursive: true, mode: 0o700 });
         // The shipped plugin follows the kit on every prepare too: a state dir from an older kit must not keep its gate.
-        for (const f of ['package.json', 'index.js']) {
+        for (const f of ['package.json', 'index.js', 'keys.js']) {
             const source = join(kitDir, 'plugin', f);
             putChanged(join(pluginDir, f), readFileSync(source, 'utf8'));
         }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.ts';
-export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, RunUsage, SignInOptions, SignInView, ToolHost, ToolSpec, } from './types.ts';
+export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, OutputSchema, SchemaOutput, RunUsage, SignInOptions, SignInView, ToolHost, ToolSpec, } from './types.ts';
 export { OpenClawKit, type KitOptions, type RetainedLogin } from './kit.ts';
+export type { AddKeyResult } from './keys.ts';
 export { stateWords, toAccountView, words, type AccountView, type WordKey } from './words.ts';
 export { EngineAlreadyRunningError } from './engine-status.ts';

package/dist/keys.d.ts

@@ -0,0 +1,20 @@
+import type { GatewayTransport, Member } from './types.ts';
+export type AddKeyResult = 'ok' | 'invalid' | 'not_included';
+export declare function createKeys(ctx: {
+    root: string;
+    request: GatewayTransport['request'];
+    ensure(member: Member): Promise<{
+        agentId: string;
+    }>;
+    restarting?(): boolean;
+}): {
+    exclusive: <T>(member: Member, work: () => Promise<T>) => Promise<T>;
+    add(member: Member, o: {
+        authChoice: string;
+        apiKey: string;
+    }): Promise<AddKeyResult>;
+    ready(member: Member): Promise<{
+        agentId: string;
+        model: string;
+    } | undefined>;
+};

package/dist/keys.js

@@ -0,0 +1,73 @@
+import { join } from 'node:path';
+import { keyAgentId, MEMBER_ID, KEY_PREFIX } from "./members.js";
+import { routes } from "./routes.js";
+export function createKeys(ctx) {
+    // Serialize key replacement and key runs, so an in-flight run never sees a half-installed replacement.
+    const tails = new Map();
+    const exclusive = async (member, work) => {
+        const previous = tails.get(member) ?? Promise.resolve();
+        const next = previous.catch(() => { }).then(work);
+        tails.set(member, next);
+        try {
+            return await next;
+        }
+        finally {
+            if (tails.get(member) === next)
+                tails.delete(member);
+        }
+    };
+    const check = (member) => MEMBER_ID.test(member) && !member.startsWith(KEY_PREFIX);
+    const control = (member, action, provider) => ctx.request('byokit.keys', { member, action, ...(provider ? { provider } : {}) });
+    return {
+        exclusive,
+        async add(member, o) {
+            if (!check(member) || !o.apiKey.trim())
+                return 'invalid';
+            const route = routes().find((r) => r.choice === o.authChoice && r.keyEntry);
+            if (!route)
+                return 'not_included';
+            return exclusive(member, async () => {
+                try {
+                    await ctx.ensure(member);
+                    const agentId = keyAgentId(member);
+                    const list = await ctx.request('agents.list');
+                    if (!list.agents.some((a) => a.id === agentId))
+                        await ctx.request('agents.create', { name: agentId, workspace: join(ctx.root, 'key-workspaces', member) });
+                    if (!(await control(member, 'prepare', route.provider)).ok)
+                        return 'invalid';
+                    // The public pin's typed API-key path, never a CLI-login import. Discard the engine's lines/errors.
+                    const params = {
+                        kind: 'api-key', agentId, authChoice: o.authChoice, apiKey: o.apiKey,
+                    };
+                    const result = (await ctx.request('openclaw.setup.activate', params, { timeoutMs: 180_000 }));
+                    if (!result.ok)
+                        return result.status === 'unavailable' ? 'not_included' : 'invalid';
+                    return (await control(member, 'seal')).ok ? 'ok' : 'invalid';
+                }
+                catch {
+                    return 'invalid';
+                }
+            });
+        },
+        async ready(member) {
+            if (!check(member))
+                return undefined;
+            const deadline = Date.now() + 60_000;
+            for (;;) {
+                try {
+                    const ready = await control(member, 'ready');
+                    return ready.ok && ready.model ? { agentId: keyAgentId(member), model: ready.model } : undefined;
+                }
+                catch (error) {
+                    // Config writes may drain/restart the gateway after activation. This read is safe to retry;
+                    // an absent profile or a terminal refusal still fails closed immediately.
+                    const refusal = error;
+                    const transient = ctx.restarting?.() || (refusal?.code === 'UNAVAILABLE' && refusal.retryable === true);
+                    if (!transient || Date.now() >= deadline)
+                        return undefined;
+                    await new Promise((resolve) => setTimeout(resolve, 250));
+                }
+            }
+        },
+    };
+}

package/dist/kit.d.ts

@@ -1,5 +1,6 @@
 import type { SealingAdapter } from '@byokit/secrets';
-import type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, Member, Route, RunEnd, RunEvent, RunSpec, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.ts';
+import { type AddKeyResult } from './keys.ts';
+import type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, Member, Route, RunEnd, RunEvent, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.ts';
 export type KitOptions = {
     stateDir: string;
     authSeal?: SealingAdapter;
@@ -47,6 +48,7 @@ export declare class OpenClawKit {
     private greeting?;
     private members?;
     private readonly bridge;
+    private readonly keys;
     private readonly approvalsCtl;
     private listeners;
     private off;
@@ -81,14 +83,24 @@ export declare class OpenClawKit {
         done: Promise<SignInView>;
     };
     signOut(member: Member, provider: string): Promise<void>;
+    /** Save an explicitly supplied API key (billed per use) in this member's separate key agent. */
+    addKey(agentId: Member, o: {
+        authChoice: string;
+        apiKey: string;
+    }): Promise<AddKeyResult>;
     migrateRetainedLogin(member: Member, source: RetainedLogin): Promise<'staged' | 'nothing' | 'failed'>;
     confirmRetainedLogin(member: Member, source: RetainedLogin): Promise<boolean>;
     private runs;
     /** The app tool names (`KitOptions.tools`): the only names `RunSpec.tools` may carry. */
     toolNames(): string[];
-    run(spec: RunSpec, on?: (e: RunEvent) => void): Promise<RunEnd>;
-    steer(sessionKey: string, text: string): Promise<void>;
-    abort(sessionKey: string): Promise<void>;
+    run<const S extends OutputSchema | undefined = undefined>(spec: RunSpec<S>, on?: (e: RunEvent) => void): Promise<RunEnd<SchemaOutput<S>>>;
+    private runKey;
+    steer(sessionKey: string, text: string, o?: {
+        auth?: 'apiKey';
+    }): Promise<void>;
+    abort(sessionKey: string, o?: {
+        auth?: 'apiKey';
+    }): Promise<void>;
     approvals(member?: Member): Approval[];
     onApproval(fn: (a: Approval, change: 'added' | 'resolved') => void): () => void;
     decide(id: string, d: Decision): Promise<void>;

package/dist/kit.js

@@ -8,8 +8,11 @@ import { Bridge } from "./bridge.js";
 import { Engine } from "./engine.js";
 import { gatewayTransport } from "./transport.js";
 import { createMembers } from "./members.js";
+import { keyAgentId, KEY_PREFIX, MEMBER_ID } from "./members.js";
 import { confirmRetainedLogin as confirmLogin, migrateRetainedLogin as migrateLogin } from "./migrate.js";
 import { createRuns } from "./runs.js";
+import { outputSchema } from "./output.js";
+import { createKeys } from "./keys.js";
 import { routes as routeTable } from "./routes.js";
 import { providers as engineProviders, signIn as startSignIn, signOut as engineSignOut } from "./signin.js";
 import { reconcileConfig, memoryLimited as configMemoryLimited } from "./config.js";
@@ -420,6 +423,7 @@ export class OpenClawKit {
     // One bridge and one approval surface per kit: listeners and run registrations survive reconnects (B3).
     // Only the socket itself is per-connection. Approvals always reaches the live transport through this.request().
     bridge;
+    keys;
     approvalsCtl;
     listeners = new Set();
     off = [];
@@ -439,6 +443,10 @@ export class OpenClawKit {
         this.engine = new Engine({ ...o, pluginId: o.plugin?.id ?? 'byokit', tools: o.tools ?? [],
             gateBuiltins: o.gateBuiltins !== false, spawnEngine: o.spawnEngine !== false,
             onState: (s) => this.setState(s), onExit: () => this.closed('engine exited') });
+        this.keys = createKeys({ root: this.engine.root,
+            restarting: () => this.current.phase === 'restarting' || this.current.phase === 'starting',
+            request: (method, params, options) => this.request()(method, params, options),
+            ensure: (member) => this.ensureMember(member) });
         const slot = {};
         this.approvalsCtl = new Approvals({
             request: (method, params, co) => this.request()(method, params, co),
@@ -599,6 +607,10 @@ export class OpenClawKit {
     signOut(member, provider) {
         return engineSignOut(this.signInCtx(), member, provider);
     }
+    /** Save an explicitly supplied API key (billed per use) in this member's separate key agent. */
+    addKey(agentId, o) {
+        return this.keys.add(agentId, o);
+    }
     migrateRetainedLogin(member, source) {
         return migrateLogin({ root: this.engine.root, prepare: () => this.prepare(), doctor: () => this.engine.doctor(120_000),
             seal: this.o.authSeal, log: this.o.log, withStore: (task) => this.engine.withAuthStore(task) }, member, source);
@@ -627,13 +639,43 @@ export class OpenClawKit {
         return (this.o.tools ?? []).map((t) => t.name);
     }
     run(spec, on) {
-        return this.runs().run(spec, on);
+        if (spec.auth !== undefined && spec.auth !== 'apiKey')
+            return Promise.reject(new Error('Choose a supported account option.'));
+        // Snapshot before account readiness awaits; invalid schemas never reach the Gateway.
+        let output;
+        try {
+            output = spec.schema === undefined ? undefined : outputSchema(spec.schema);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        if (spec.auth === 'apiKey')
+            return this.keys.exclusive(spec.member, async () => {
+                if (!spec.sessionKey.startsWith(`agent:${spec.member}:`))
+                    throw new Error('This conversation belongs to another member.');
+                const selected = await this.keys.ready(spec.member);
+                if (!selected)
+                    return { ok: false, kind: 'signed-out', message: 'Add an API key to use this option.' };
+                if (spec.model !== undefined && spec.model !== selected.model)
+                    return { ok: false, kind: 'plan', message: 'Choose the model saved with this key.' };
+                // RunRef.member stays the person for app gates; the engine receives the isolated agent and history.
+                return this.runs().run({ ...spec, model: selected.model }, on, selected.agentId, output);
+            });
+        return this.runs().run(spec, on, undefined, output);
+    }
+    runKey(sessionKey, o) {
+        if (o?.auth !== 'apiKey')
+            return sessionKey;
+        const [, member, tail] = /^agent:([^:]+):(.*)$/.exec(sessionKey) ?? [];
+        if (!member || !MEMBER_ID.test(member) || member.startsWith(KEY_PREFIX))
+            throw new Error('Choose your own conversation.');
+        return `agent:${keyAgentId(member)}:${tail}`;
     }
-    steer(sessionKey, text) {
-        return this.runs().steer(sessionKey, text);
+    steer(sessionKey, text, o) {
+        return this.runs().steer(this.runKey(sessionKey, o), text);
     }
-    abort(sessionKey) {
-        return this.runs().abort(sessionKey);
+    abort(sessionKey, o) {
+        return this.runs().abort(this.runKey(sessionKey, o));
     }
     // approvals (5.9)
     approvals(member) {

package/dist/link.js

@@ -10,6 +10,7 @@ import { ENGINE_VERSION } from "./constants.js";
 import { b64urlDecode, sealNotice } from "./notices.js";
 import { routeFor } from "./routes.js";
 import { authStatus } from "./auth-status.js";
+import { outputSchema } from "./output.js";
 import { signedInProviders } from "./runs.js";
 import { stateWords, words } from "./words.js";
 const VIEW_OPS = new Set(['oc.state', 'oc.routes', 'oc.signin.view', 'oc.sessions', 'oc.approvals', 'oc.events']);
@@ -25,18 +26,23 @@ function memberSessions(result, member) {
 }
 /** `oc.run`'s run options, type-checked; the kit's own checks (account, tool names) still apply. */
 function runOptions(args) {
-    const { message, model, system, images, thinking, tools } = args;
+    const { message, model, auth, system, images, thinking, tools, schema } = args;
     const ok = typeof message === 'string'
         && (model === undefined || typeof model === 'string')
+        && (auth === undefined || auth === 'apiKey')
         && (system === undefined || typeof system === 'string')
         && (images === undefined || (Array.isArray(images) && images.every((i) => isRecord(i) && typeof i.data === 'string' && typeof i.mimeType === 'string')))
         && (thinking === undefined || (typeof thinking === 'string' && THINKING.has(thinking)))
         && (tools === undefined || (Array.isArray(tools) && tools.every((t) => typeof t === 'string')));
     if (!ok)
-        throw new Error('oc.run needs { message, sessionKey?, model?, system?, images?, thinking?, tools? }');
+        throw new Error('oc.run needs { message, sessionKey?, model?, auth?, system?, images?, thinking?, tools?, schema? }');
+    if (schema !== undefined)
+        outputSchema(schema);
     return {
         message: message,
+        ...(schema === undefined ? {} : { schema: schema }),
         ...(model === undefined ? {} : { model: model }),
+        ...(auth === undefined ? {} : { auth: 'apiKey' }),
         ...(system === undefined ? {} : { system: system }),
         ...(images === undefined ? {} : { images: images
                 .map((i) => ({ data: i.data, mimeType: i.mimeType })) }),
@@ -180,19 +186,19 @@ export function openclawLink(kit, o) {
                 return memberSessions(result, member);
             }
             case 'oc.steer': {
-                if (typeof args.sessionKey !== 'string' || typeof args.text !== 'string')
+                if (typeof args.sessionKey !== 'string' || typeof args.text !== 'string' || (args.auth !== undefined && args.auth !== 'apiKey'))
                     throw new Error('oc.steer needs { sessionKey, text }');
                 if (!memberKey(member, args.sessionKey))
                     throw refused();
-                await kit.steer(args.sessionKey, args.text);
+                await kit.steer(args.sessionKey, args.text, args.auth === 'apiKey' ? { auth: 'apiKey' } : undefined);
                 return null;
             }
             case 'oc.abort': {
-                if (typeof args.sessionKey !== 'string')
+                if (typeof args.sessionKey !== 'string' || (args.auth !== undefined && args.auth !== 'apiKey'))
                     throw new Error('oc.abort needs { sessionKey }');
                 if (!memberKey(member, args.sessionKey))
                     throw refused();
-                await kit.abort(args.sessionKey);
+                await kit.abort(args.sessionKey, args.auth === 'apiKey' ? { auth: 'apiKey' } : undefined);
                 return null;
             }
             case 'oc.approvals':

package/dist/members.d.ts

@@ -1,5 +1,7 @@
 import type { GatewayTransport, Member } from './types.ts';
 export declare const MEMBER_ID: RegExp;
+export declare const KEY_PREFIX = "byokit-key-";
+export declare const keyAgentId: (member: Member) => string;
 export declare function createMembers(ctx: {
     request: GatewayTransport['request'];
     root: string;

package/dist/members.js

@@ -1,9 +1,11 @@
 import { join } from 'node:path';
 export const MEMBER_ID = /^[a-z][a-z0-9-]{0,31}$/;
+export const KEY_PREFIX = 'byokit-key-';
+export const keyAgentId = (member) => `${KEY_PREFIX}${member}`;
 export function createMembers(ctx) {
     const cache = new Map();
     return { ensure(member) {
-            if (!MEMBER_ID.test(member))
+            if (!MEMBER_ID.test(member) || member.startsWith(KEY_PREFIX))
                 return Promise.reject(new Error(`invalid member id: ${member}`));
             const existing = cache.get(member);
             if (existing)

package/dist/output.d.ts

@@ -0,0 +1,68 @@
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+type JsonType = 'null' | 'boolean' | 'number' | 'integer' | 'string' | 'array' | 'object';
+type SchemaNode = boolean | OutputSchema;
+export type OutputSchema = {
+    readonly type?: JsonType | readonly JsonType[];
+    readonly properties?: Readonly<Record<string, SchemaNode>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: SchemaNode;
+    readonly items?: SchemaNode;
+    readonly enum?: readonly JsonValue[];
+    readonly const?: JsonValue;
+    readonly anyOf?: readonly SchemaNode[];
+    readonly oneOf?: readonly SchemaNode[];
+    readonly allOf?: readonly SchemaNode[];
+    readonly not?: SchemaNode;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly exclusiveMinimum?: number;
+    readonly exclusiveMaximum?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly uniqueItems?: boolean;
+    readonly minProperties?: number;
+    readonly maxProperties?: number;
+    readonly title?: string;
+    readonly description?: string;
+    readonly default?: JsonValue;
+    readonly examples?: readonly JsonValue[];
+    readonly $schema?: 'http://json-schema.org/draft-07/schema#';
+};
+type KeysInEveryList<R extends readonly string[]> = (R extends unknown ? (key: number extends R['length'] ? never : R[number]) => void : never) extends (key: infer K) => void ? Extract<K, string> : never;
+type RequiredKeys<S> = S extends {
+    readonly required: infer R extends readonly string[];
+} ? KeysInEveryList<R> : never;
+type ObjectOutput<S> = S extends {
+    readonly properties: infer P extends Record<string, SchemaNode>;
+} ? {
+    -readonly [K in keyof P as K extends RequiredKeys<S> ? K : never]: SchemaOutput<P[K]>;
+} & {
+    -readonly [K in keyof P as K extends RequiredKeys<S> ? never : K]?: SchemaOutput<P[K]>;
+} : Record<string, unknown>;
+type OutputType<T, S> = T extends 'null' ? null : T extends 'boolean' ? boolean : T extends 'number' | 'integer' ? number : T extends 'string' ? string : T extends 'array' ? (S extends {
+    readonly items: infer I;
+} ? SchemaOutput<I> : unknown)[] : T extends 'object' ? ObjectOutput<S> : unknown;
+/** Literal schemas infer their output; broad/dynamic schemas and unsupported inference shapes remain unknown. */
+export type SchemaOutput<S> = S extends {
+    readonly const: infer V;
+} ? V : S extends {
+    readonly enum: readonly (infer V)[];
+} ? V : S extends {
+    readonly type: infer T;
+} ? OutputType<T extends readonly unknown[] ? T[number] : T, S> : S extends {
+    readonly anyOf: readonly (infer B)[];
+} | {
+    readonly oneOf: readonly (infer B)[];
+} ? SchemaOutput<B> : unknown;
+/** Snapshot a JSON-only schema before any await; no mutation can change the prompt or its validation. */
+export declare function outputSchema(value: unknown): {
+    prompt: string;
+    parse(text: string): {
+        data: unknown;
+    } | undefined;
+};
+export {};