@byokit/openclaw 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## 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.

package/README.md

@@ -94,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:
 

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,8 +19,13 @@ 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';
@@ -61,10 +66,7 @@ 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;
-    }>;
+    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>;

package/dist/device.js

@@ -141,7 +141,7 @@ export function openclawDevice(link) {
                 ...(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]() {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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';

package/dist/kit.d.ts

@@ -1,6 +1,6 @@
 import type { SealingAdapter } from '@byokit/secrets';
 import { type AddKeyResult } from './keys.ts';
-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 { 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;
@@ -93,7 +93,7 @@ export declare class OpenClawKit {
     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>;
+    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';

package/dist/kit.js

@@ -11,6 +11,7 @@ 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";
@@ -640,6 +641,14 @@ export class OpenClawKit {
     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}:`))
@@ -650,9 +659,9 @@ export class OpenClawKit {
                 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);
+                return this.runs().run({ ...spec, model: selected.model }, on, selected.agentId, output);
             });
-        return this.runs().run(spec, on);
+        return this.runs().run(spec, on, undefined, output);
     }
     runKey(sessionKey, o) {
         if (o?.auth !== 'apiKey')

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,7 +26,7 @@ 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, auth, 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')
@@ -34,9 +35,12 @@ function runOptions(args) {
         && (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 }),

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 {};

package/dist/output.js

@@ -0,0 +1,166 @@
+const record = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const own = (v, k) => Object.hasOwn(v, k);
+const types = new Set(['null', 'boolean', 'number', 'integer', 'string', 'array', 'object']);
+const bounds = ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum'];
+const counts = ['minLength', 'maxLength', 'minItems', 'maxItems', 'minProperties', 'maxProperties'];
+const annotations = ['title', 'description', 'default', 'examples', '$schema'];
+const keywords = new Set(['type', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'const',
+    'anyOf', 'oneOf', 'allOf', 'not', 'uniqueItems', ...bounds, ...counts, ...annotations]);
+function invalid() { throw new Error('refused: invalid or unsupported output schema'); }
+function checkSchema(s, depth = 0) {
+    if (depth > 32)
+        invalid();
+    if (typeof s === 'boolean')
+        return;
+    if (!record(s) || Object.keys(s).some((k) => !keywords.has(k)))
+        invalid();
+    if (own(s, 'type')) {
+        const ts = Array.isArray(s.type) ? s.type : [s.type];
+        if (!ts.length || ts.some((t) => !types.has(t)) || new Set(ts).size !== ts.length)
+            invalid();
+    }
+    for (const k of bounds)
+        if (own(s, k) && (typeof s[k] !== 'number' || !Number.isFinite(s[k])))
+            invalid();
+    for (const k of counts)
+        if (own(s, k) && (typeof s[k] !== 'number' || !Number.isSafeInteger(s[k]) || s[k] < 0))
+            invalid();
+    for (const k of ['title', 'description'])
+        if (own(s, k) && typeof s[k] !== 'string')
+            invalid();
+    if (own(s, '$schema') && s.$schema !== 'http://json-schema.org/draft-07/schema#')
+        invalid();
+    if (own(s, 'examples') && !Array.isArray(s.examples))
+        invalid();
+    if (own(s, 'enum') && (!Array.isArray(s.enum) || !s.enum.length))
+        invalid();
+    if (own(s, 'uniqueItems') && typeof s.uniqueItems !== 'boolean')
+        invalid();
+    if (own(s, 'required') && (!Array.isArray(s.required) || s.required.some((k) => typeof k !== 'string')
+        || new Set(s.required).size !== s.required.length))
+        invalid();
+    if (own(s, 'properties')) {
+        if (!record(s.properties))
+            invalid();
+        for (const sub of Object.values(s.properties))
+            checkSchema(sub, depth + 1);
+    }
+    for (const k of ['items', 'additionalProperties', 'not'])
+        if (own(s, k))
+            checkSchema(s[k], depth + 1);
+    for (const k of ['anyOf', 'oneOf', 'allOf'])
+        if (own(s, k)) {
+            if (!Array.isArray(s[k]) || !s[k].length)
+                invalid();
+            for (const sub of s[k])
+                checkSchema(sub, depth + 1);
+        }
+}
+// Equality is structural: JSON objects have no key order, including enum/const values and unique array items.
+function equal(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((v, i) => equal(v, b[i]));
+    if (record(a) && record(b))
+        return Object.keys(a).length === Object.keys(b).length
+            && Object.keys(a).every((k) => own(b, k) && equal(a[k], b[k]));
+    return false;
+}
+function hasType(v, t) {
+    if (t === 'null')
+        return v === null;
+    if (t === 'array')
+        return Array.isArray(v);
+    if (t === 'object')
+        return record(v);
+    if (t === 'integer')
+        return typeof v === 'number' && Number.isInteger(v);
+    return typeof v === t && (t !== 'number' || Number.isFinite(v));
+}
+function matches(s, v) {
+    if (typeof s === 'boolean')
+        return s;
+    if (s.type !== undefined && !(Array.isArray(s.type) ? s.type : [s.type]).some((t) => hasType(v, t)))
+        return false;
+    if (own(s, 'const') && !equal(s.const, v))
+        return false;
+    if (s.enum && !s.enum.some((e) => equal(e, v)))
+        return false;
+    if (s.allOf && !s.allOf.every((sub) => matches(sub, v)))
+        return false;
+    if (s.anyOf && !s.anyOf.some((sub) => matches(sub, v)))
+        return false;
+    if (s.oneOf && s.oneOf.filter((sub) => matches(sub, v)).length !== 1)
+        return false;
+    if (s.not !== undefined && matches(s.not, v))
+        return false;
+    if (typeof v === 'number') {
+        if (!Number.isFinite(v) || (s.minimum !== undefined && v < s.minimum) || (s.maximum !== undefined && v > s.maximum)
+            || (s.exclusiveMinimum !== undefined && v <= s.exclusiveMinimum) || (s.exclusiveMaximum !== undefined && v >= s.exclusiveMaximum))
+            return false;
+    }
+    if (typeof v === 'string') {
+        const length = [...v].length;
+        if ((s.minLength !== undefined && length < s.minLength) || (s.maxLength !== undefined && length > s.maxLength))
+            return false;
+    }
+    if (Array.isArray(v)) {
+        if ((s.minItems !== undefined && v.length < s.minItems) || (s.maxItems !== undefined && v.length > s.maxItems))
+            return false;
+        if (s.items !== undefined && !v.every((item) => matches(s.items, item)))
+            return false;
+        if (s.uniqueItems && v.some((item, i) => v.slice(0, i).some((other) => equal(item, other))))
+            return false;
+    }
+    if (record(v)) {
+        const keys = Object.keys(v);
+        if ((s.minProperties !== undefined && keys.length < s.minProperties) || (s.maxProperties !== undefined && keys.length > s.maxProperties))
+            return false;
+        if (s.required?.some((k) => !own(v, k)))
+            return false;
+        for (const k of keys) {
+            const sub = s.properties && own(s.properties, k) ? s.properties[k] : s.additionalProperties;
+            if (sub !== undefined && !matches(sub, v[k]))
+                return false;
+        }
+    }
+    return true;
+}
+/** Snapshot a JSON-only schema before any await; no mutation can change the prompt or its validation. */
+export function outputSchema(value) {
+    let json;
+    try {
+        json = JSON.stringify(value, (_key, v) => {
+            if (v === undefined || typeof v === 'function' || typeof v === 'symbol' || typeof v === 'bigint'
+                || (typeof v === 'number' && !Number.isFinite(v)))
+                invalid();
+            return v;
+        });
+    }
+    catch {
+        invalid();
+    }
+    if (!json || json.length > 65_536 || new TextEncoder().encode(json).length > 65_536)
+        invalid();
+    const schema = JSON.parse(json);
+    if (!record(schema))
+        invalid(); // the public run contract requires an object at its root
+    checkSchema(schema);
+    return {
+        prompt: `Return only one JSON value matching this JSON Schema, with no markdown or surrounding text.\n${json}`,
+        parse: (text) => {
+            try {
+                const data = JSON.parse(text, (_key, value) => {
+                    if (typeof value === 'number' && !Number.isFinite(value))
+                        throw new Error('invalid number');
+                    return value;
+                });
+                return matches(schema, data) ? { data } : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}

package/dist/runs.d.ts

@@ -1,4 +1,5 @@
 import type { Bridge } from './bridge.ts';
+import { outputSchema, type OutputSchema, type SchemaOutput } from './output.ts';
 import type { GatewayTransport, Member, RunEnd, RunEvent, RunSpec } from './types.ts';
 /**
  * The providers a `models.authStatus` answer shows usable (the rule a picked account is checked by), lowercased and
@@ -14,7 +15,7 @@ export declare function createRuns(ctx: {
     bridge: Pick<Bridge, 'register'>;
     tools: ReadonlySet<string>;
 }): {
-    run(spec: RunSpec, on?: (e: RunEvent) => void, keyAgent?: string): Promise<RunEnd>;
+    run<const S extends OutputSchema | undefined = undefined>(spec: RunSpec<S>, on?: (e: RunEvent) => void, keyAgent?: string, preparedOutput?: ReturnType<typeof outputSchema>): Promise<RunEnd<SchemaOutput<S>>>;
     steer(k: string, t: string): Promise<void>;
     abort(k: string): Promise<void>;
 };

package/dist/runs.js

@@ -2,6 +2,8 @@
 import { randomUUID } from 'node:crypto';
 import { setTimeout as delay } from 'node:timers/promises';
 import { authStatus } from "./auth-status.js";
+import { outputSchema } from "./output.js";
+import { words } from "./words.js";
 import { classify } from "./classify.js";
 // The gateway gives up on a silent run after an hour; we wait ten minutes longer for the reply frame itself.
 const WAIT_MS = 3_600_000;
@@ -78,10 +80,12 @@ export function createRuns(ctx) {
             return undefined;
         }
     };
-    const run = async (spec, on, keyAgent) => {
+    const run = async (spec, on, keyAgent, preparedOutput) => {
         // Member boundary first: a member never speaks in another member's session, refused before any request.
         if (!spec.sessionKey.startsWith(`agent:${spec.member}:`))
             throw new Error(`refused: "${spec.sessionKey}" is not a session of member "${spec.member}"`);
+        const output = preparedOutput ?? (spec.schema === undefined ? undefined : outputSchema(spec.schema));
+        const system = [spec.system, output?.prompt].filter(Boolean).join('\n\n');
         const picked = spec.model === undefined ? undefined : account(spec.model);
         for (const tool of spec.tools ?? [])
             if (!ctx.tools.has(tool))
@@ -89,7 +93,7 @@ export function createRuns(ctx) {
         const agentId = keyAgent ?? (await ctx.ensure(spec.member)).agentId;
         const sessionKey = keyAgent ? `agent:${keyAgent}:${spec.sessionKey.slice(`agent:${spec.member}:`.length)}` : spec.sessionKey;
         const release = spec.register !== false ? ctx.bridge.register({ sessionKey, member: spec.member }, spec.tools) : undefined;
-        let last = '';
+        let last;
         let runId = ''; // gateway events for other runs carry a real runId and never match the empty one
         let ended = false;
         // The engine flags an aborted run on its lifecycle end event; the wait receipt itself only says
@@ -153,7 +157,7 @@ export function createRuns(ctx) {
                 message: spec.message,
                 idempotencyKey: randomUUID(),
                 ...(picked ?? {}),
-                ...(spec.system ? { extraSystemPrompt: spec.system } : {}),
+                ...(system ? { extraSystemPrompt: system } : {}),
                 ...(spec.images ? { attachments: spec.images.map((image) => ({ mimeType: image.mimeType, content: image.data })) } : {}),
                 ...(spec.thinking ? { thinking: spec.thinking } : {}),
             }, { expectFinal: true, timeoutMs: WAIT_CLIENT_MS, onAccepted });
@@ -162,15 +166,28 @@ export function createRuns(ctx) {
             runId = started.runId;
             const result = await ctx.request('agent.wait', { runId, timeoutMs: WAIT_MS }, { timeoutMs: WAIT_CLIENT_MS });
             if (result.status === 'ok') {
-                const text = typeof result.terminalReply?.text === 'string' ? result.terminalReply.text : last;
-                on?.({ type: 'text', text }); // the final cumulative text
                 const done = await Promise.race([final.catch(() => undefined), delay(FINAL_GRACE_MS, undefined, { ref: false })]);
-                const meta = isRecord(done) && isRecord(done.result) && isRecord(done.result.meta) ? done.result.meta : {};
+                ended = true; // no later stream event may supersede the final callback
+                const frame = isRecord(done) && isRecord(done.result) ? done.result : {};
+                const payloadText = Array.isArray(frame.payloads)
+                    ? frame.payloads.filter((p) => isRecord(p) && typeof p.text === 'string')
+                        .map((p) => p.text) : [];
+                // The pin's terminal snapshot is capped display evidence, not the complete generated answer.
+                // Its silent/empty disposition still controls visibility, even after transient streamed text.
+                const terminal = result.terminalReply;
+                const text = terminal?.disposition === 'silent' || terminal?.disposition === 'empty' ? ''
+                    : payloadText.length ? payloadText.join('\n\n')
+                        : last ?? (typeof terminal?.text === 'string' ? terminal.text : '');
+                on?.({ type: 'text', text }); // the final cumulative text (unvalidated)
+                const parsed = output?.parse(text);
+                if (output && !parsed)
+                    return { ok: false, kind: 'output', message: words('member.output') };
+                const meta = isRecord(frame.meta) ? frame.meta : {};
                 const agentMeta = isRecord(meta.agentMeta) ? meta.agentMeta : {};
                 const usage = usageOf(agentMeta);
                 const planWindow = typeof agentMeta.provider === 'string'
                     ? await planWindowOf(agentId, agentMeta.provider.toLowerCase()) : undefined;
-                return { ok: true, text, ...(usage ? { usage } : {}), ...(planWindow ? { planWindow } : {}) };
+                return { ok: true, text, ...(parsed ? { data: parsed.data } : {}), ...(usage ? { usage } : {}), ...(planWindow ? { planWindow } : {}) };
             }
             if (result.stopReason === 'aborted' || (abortedByEngine && result.status !== 'ok'))
                 return { ok: false, aborted: true };

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+import type { OutputSchema } from './output.ts';
+export type { OutputSchema, SchemaOutput } from './output.ts';
 export type Member = string;
 export interface ToolSpec {
     name: string;
@@ -25,8 +27,9 @@ export interface ToolHost {
     }): Promise<GateResult>;
     call(run: RunRef, tool: string, input: Record<string, unknown>, signal: AbortSignal): Promise<string>;
 }
-export interface RunSpec extends RunRef {
+export interface RunSpec<S extends OutputSchema | undefined = OutputSchema | undefined> extends RunRef {
     message: string;
+    schema?: S;
     system?: string;
     images?: {
         data: string;
@@ -71,9 +74,10 @@ export type PlanWindow = {
         resetAt?: number;
     }[];
 };
-export type RunEnd = {
+export type RunEnd<T = unknown> = {
     ok: true;
     text: string;
+    data?: T;
     usage?: RunUsage;
     planWindow?: PlanWindow;
 } | {
@@ -81,7 +85,7 @@ export type RunEnd = {
     aborted: true;
 } | {
     ok: false;
-    kind: 'signed-out' | 'resting' | 'plan' | 'network' | 'other';
+    kind: 'signed-out' | 'resting' | 'plan' | 'network' | 'other' | 'output';
     until?: number;
     message: string;
 };

package/dist/types.js

@@ -1,2 +1 @@
-// Public types for the OpenClaw runtime kit (docs/runtime-kits.md 5.2). Types only; behavior lives in the modules.
 export {};

package/dist/words.json

@@ -11,6 +11,7 @@
     "member.signedOut": "Sign in with {name} to start.",
     "member.resting": "{name} needs a break until {time}.",
     "member.plan": "Your {name} plan doesn't include this.",
+    "member.output": "The answer did not match the requested format.",
     "member.network": "Can't reach {name} right now. This keeps trying by itself.",
     "signin.returned": "Thanks. Finishing the sign-in — you can go back to the app now.",
     "signin.busy": "Another sign-in is already in progress. Finish or cancel it, then try again.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
   "license": "Apache-2.0",
   "type": "module",
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@byokit/link": "0.7.0",
-    "@byokit/relay": "0.5.0",
+    "@byokit/relay": "0.5.1",
     "@byokit/reach": "0.6.0",
     "@byokit/seal": "0.2.0",
     "@byokit/secrets": "0.5.0",