@holon-run/uxc-daemon-client 0.12.8 → 0.13.3

package/dist/index.cjs

@@ -31,7 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   DaemonRpcError: () => DaemonRpcError,
-  UxcDaemonClient: () => UxcDaemonClient
+  UxcDaemonClient: () => UxcDaemonClient,
+  generateTypeScriptClient: () => generateTypeScriptClient
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_child_process = require("child_process");
@@ -82,7 +83,38 @@ var UxcDaemonClient = class {
       options: normalizeOptions(args.options)
     });
   }
+  async codegenSchema(args) {
+    const response = await this.request("runtime.invoke", {
+      request_id: requestId("codegen"),
+      endpoint: args.endpoint,
+      action: "codegen_schema",
+      operation_id: null,
+      args: null,
+      options: normalizeOptions(args.options)
+    });
+    if (response.kind !== "codegen_host_schema") {
+      throw new Error(
+        `Unexpected codegen response kind '${response.kind}' (expected codegen_host_schema)`
+      );
+    }
+    assertCodegenHostSchema(response.data);
+    return response.data;
+  }
+  async generateTypeScriptClient(args) {
+    const schema = await this.codegenSchema({
+      endpoint: args.endpoint,
+      options: args.options
+    });
+    return generateTypeScriptClient(schema, args.emitter);
+  }
   async subscribeStart(args) {
+    const mode = args.mode ?? (args.pollConfig ? "poll" : "stream");
+    if (mode === "poll" && !args.pollConfig) {
+      throw new Error("pollConfig is required when mode is 'poll'");
+    }
+    if (mode !== "poll" && args.pollConfig) {
+      throw new Error("pollConfig is only valid when mode is 'poll'");
+    }
     return this.request("subscription.start", {
       request_id: requestId("subscribe"),
       endpoint: args.endpoint,
@@ -94,8 +126,8 @@ var UxcDaemonClient = class {
       transport_hint: args.transportHint ?? null,
       subprotocols: [],
       initial_text_frames: [],
-      mode: args.mode ?? "stream",
-      poll_config: null,
+      mode,
+      poll_config: args.pollConfig ?? null,
       ephemeral: args.ephemeral ?? (args.sink ?? "memory:") === "memory:",
       options: normalizeOptions(args.options)
     });
@@ -229,6 +261,361 @@ var UxcDaemonClient = class {
     return response;
   }
 };
+function generateTypeScriptClient(schema, options = {}) {
+  const packageImport = options.packageImport ?? "@holon-run/uxc-daemon-client";
+  const className = sanitizeTypeName(options.className ?? defaultClassName(schema.host.id));
+  const methodNames = /* @__PURE__ */ new Set();
+  const typeNames = /* @__PURE__ */ new Set();
+  const operationBlocks = [];
+  const typeBlocks = [];
+  for (const operation of schema.operations) {
+    if (!operation.execute || operation.help_only || operation.subscribable) {
+      continue;
+    }
+    const methodName = uniqueName(
+      sanitizeMethodName(defaultMethodName(operation.id)),
+      methodNames
+    );
+    const typeName = uniqueName(
+      sanitizeTypeName(`${upperFirst(methodName)}Input`),
+      typeNames
+    );
+    const selectedInputSchema = selectOperationInputSchema(operation.input_schema);
+    const inputType = selectedInputSchema ? renderTsTypeFromSchema(selectedInputSchema, 0) : "Record<string, unknown>";
+    const inputRequired = selectedInputSchema ? hasRequiredInput(selectedInputSchema) : false;
+    typeBlocks.push(`export type ${typeName} = ${inputType};`);
+    operationBlocks.push(
+      [
+        `  async ${methodName}(`,
+        inputRequired ? `    input: ${typeName},` : `    input?: ${typeName},`,
+        `    options: RuntimeInvokeOptions = {},`,
+        `  ): Promise<RuntimeResult<unknown>> {`,
+        `    return this.client.call({`,
+        `      endpoint: this.endpoint,`,
+        `      operation: ${JSON.stringify(operation.id)},`,
+        `      payload: toRuntimePayload(input),`,
+        `      options: { ...this.defaultOptions, ...options },`,
+        `    }) as Promise<RuntimeResult<unknown>>;`,
+        `  }`
+      ].join("\n")
+    );
+  }
+  const lines = [
+    `import { UxcDaemonClient, type RuntimeInvokeOptions, type RuntimeResult } from ${JSON.stringify(packageImport)};`,
+    "",
+    ...typeBlocks,
+    "",
+    `export interface ${className}Options {`,
+    "  client?: UxcDaemonClient;",
+    "  endpoint?: string;",
+    "  defaultOptions?: RuntimeInvokeOptions;",
+    "}",
+    "",
+    `export class ${className} {`,
+    "  readonly client: UxcDaemonClient;",
+    "  readonly endpoint: string;",
+    "  readonly defaultOptions: RuntimeInvokeOptions;",
+    "",
+    `  constructor(options: ${className}Options = {}) {`,
+    "    this.client = options.client ?? new UxcDaemonClient();",
+    `    this.endpoint = options.endpoint ?? ${JSON.stringify(schema.host.endpoint)};`,
+    "    this.defaultOptions = options.defaultOptions ?? {};",
+    "  }",
+    "",
+    ...operationBlocks,
+    "}",
+    "",
+    "function toRuntimePayload(input: unknown): Record<string, unknown> | undefined {",
+    "  if (input == null) {",
+    "    return undefined;",
+    "  }",
+    '  if (typeof input === "object" && !Array.isArray(input)) {',
+    "    return input as Record<string, unknown>;",
+    "  }",
+    "  return { body: input };",
+    "}"
+  ];
+  if (options.includeSchemaJson) {
+    lines.push(
+      "",
+      `export const GENERATED_SCHEMA = ${JSON.stringify(schema, null, 2)} as const;`
+    );
+  }
+  return `${lines.join("\n")}
+`;
+}
+function defaultClassName(hostId) {
+  return `${sanitizeTypeName(hostId)}Client`;
+}
+function defaultMethodName(operationId) {
+  const openApiMatch = operationId.match(/^([a-z]+):\/(.*)$/i);
+  if (openApiMatch) {
+    const verb = openApiMatch[1].toLowerCase();
+    const path = openApiMatch[2].replace(/\{([^}]+)\}/g, " by $1 ").replace(/[/:_-]+/g, " ");
+    return `${verb} ${path}`;
+  }
+  return operationId.replace(/[/:._-]+/g, " ");
+}
+function sanitizeMethodName(raw) {
+  const tokens = raw.replace(/[^a-zA-Z0-9]+/g, " ").trim().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) {
+    return "invoke";
+  }
+  const [first, ...rest] = tokens;
+  const normalized = [first.toLowerCase(), ...rest.map((token) => upperFirst(token.toLowerCase()))].join(
+    ""
+  );
+  return /^[a-zA-Z_$]/.test(normalized) ? normalized : `op${upperFirst(normalized)}`;
+}
+function sanitizeTypeName(raw) {
+  if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(raw)) {
+    return raw;
+  }
+  const tokens = raw.replace(/[^a-zA-Z0-9]+/g, " ").trim().split(/\s+/).filter(Boolean).map((token) => upperFirst(token));
+  const candidate = tokens.join("") || "Generated";
+  return /^[A-Za-z_$]/.test(candidate) ? candidate : `T${candidate}`;
+}
+function upperFirst(input) {
+  if (input.length === 0) {
+    return input;
+  }
+  return `${input[0].toUpperCase()}${input.slice(1)}`;
+}
+function uniqueName(name, used) {
+  let candidate = name;
+  let idx = 2;
+  while (used.has(candidate)) {
+    candidate = `${name}${idx}`;
+    idx += 1;
+  }
+  used.add(candidate);
+  return candidate;
+}
+function hasRequiredInput(schema) {
+  if (!schema || typeof schema !== "object") {
+    return false;
+  }
+  const required = schema.required;
+  return Array.isArray(required) && required.length > 0;
+}
+function selectOperationInputSchema(inputSchema) {
+  if (!inputSchema || typeof inputSchema !== "object") {
+    return void 0;
+  }
+  const obj = inputSchema;
+  if (obj.kind === "grpc_message" && typeof obj.schema === "object") {
+    return obj.schema;
+  }
+  if (obj.kind === "openrpc_method" && Array.isArray(obj.params)) {
+    const properties = {};
+    const required = [];
+    for (const raw of obj.params) {
+      if (!raw || typeof raw !== "object") {
+        continue;
+      }
+      const param = raw;
+      const name = typeof param.name === "string" ? param.name : void 0;
+      if (!name) {
+        continue;
+      }
+      const schema = typeof param.schema === "object" ? param.schema : {};
+      properties[name] = schema;
+      if (param.required === true) {
+        required.push(name);
+      }
+    }
+    return { type: "object", properties, required };
+  }
+  if (obj.kind === "openapi_request_body" && obj.content && typeof obj.content === "object") {
+    const content = obj.content;
+    const prioritized = [
+      "application/json",
+      "application/x-www-form-urlencoded",
+      "multipart/form-data"
+    ];
+    for (const mime of prioritized) {
+      const entry = content[mime];
+      if (entry && typeof entry === "object" && entry.schema) {
+        return entry.schema;
+      }
+    }
+    for (const entry of Object.values(content)) {
+      if (entry && typeof entry === "object" && entry.schema) {
+        return entry.schema;
+      }
+    }
+  }
+  if (typeof obj.schema === "object" && obj.type == null) {
+    return obj.schema;
+  }
+  return inputSchema;
+}
+function renderTsTypeFromSchema(schema, depth) {
+  if (!schema || typeof schema !== "object") {
+    return "Record<string, unknown>";
+  }
+  const obj = schema;
+  const typeInfo = resolveSchemaType(obj.type);
+  const enumValues = asPrimitiveArray(obj.enum);
+  if (enumValues && enumValues.length > 0) {
+    return withNullable(
+      enumValues.map((value) => JSON.stringify(value)).join(" | "),
+      typeInfo.nullable
+    );
+  }
+  if (Array.isArray(obj.oneOf) && obj.oneOf.length > 0) {
+    return withNullable(
+      obj.oneOf.map((item) => renderTsTypeFromSchema(item, depth + 1)).join(" | "),
+      typeInfo.nullable
+    );
+  }
+  if (Array.isArray(obj.anyOf) && obj.anyOf.length > 0) {
+    return withNullable(
+      obj.anyOf.map((item) => renderTsTypeFromSchema(item, depth + 1)).join(" | "),
+      typeInfo.nullable
+    );
+  }
+  const schemaType = typeInfo.base;
+  const openApiNullable = obj.nullable === true;
+  switch (schemaType) {
+    case "string":
+      return withNullable("string", typeInfo.nullable || openApiNullable);
+    case "integer":
+    case "number":
+      return withNullable("number", typeInfo.nullable || openApiNullable);
+    case "boolean":
+      return withNullable("boolean", typeInfo.nullable || openApiNullable);
+    case "null":
+      return "null";
+    case "array": {
+      const itemType = renderTsTypeFromSchema(obj.items, depth + 1);
+      return withNullable(`Array<${itemType}>`, typeInfo.nullable || openApiNullable);
+    }
+    case "object": {
+      const properties = obj.properties;
+      if (!properties || typeof properties !== "object") {
+        return withNullable("Record<string, unknown>", typeInfo.nullable || openApiNullable);
+      }
+      if (depth > 4) {
+        return withNullable("Record<string, unknown>", typeInfo.nullable || openApiNullable);
+      }
+      const required = new Set(
+        Array.isArray(obj.required) ? obj.required.filter((item) => typeof item === "string") : []
+      );
+      const fields = Object.entries(properties).map(([name, value]) => {
+        const optional = required.has(name) ? "" : "?";
+        const key = safePropertyName(name);
+        const valueType = renderTsTypeFromSchema(value, depth + 1);
+        return `${key}${optional}: ${valueType}`;
+      });
+      if (fields.length === 0) {
+        return withNullable("Record<string, unknown>", typeInfo.nullable || openApiNullable);
+      }
+      return withNullable(`{ ${fields.join("; ")} }`, typeInfo.nullable || openApiNullable);
+    }
+    default:
+      return withNullable("unknown", typeInfo.nullable || openApiNullable);
+  }
+}
+function resolveSchemaType(typeValue) {
+  if (typeof typeValue === "string") {
+    return {
+      base: typeValue,
+      nullable: typeValue === "null"
+    };
+  }
+  if (Array.isArray(typeValue)) {
+    const nullable = typeValue.some((entry) => entry === "null");
+    const nonNull = typeValue.find(
+      (entry) => typeof entry === "string" && entry !== "null"
+    );
+    return {
+      base: nonNull,
+      nullable
+    };
+  }
+  return {
+    base: void 0,
+    nullable: false
+  };
+}
+function asPrimitiveArray(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const allPrimitive = value.every(
+    (item) => item == null || typeof item === "string" || typeof item === "number" || typeof item === "boolean"
+  );
+  return allPrimitive ? value : void 0;
+}
+function safePropertyName(name) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+function withNullable(type, nullable) {
+  if (!nullable || type.includes("null")) {
+    return type;
+  }
+  return `${type} | null`;
+}
+function assertCodegenHostSchema(value) {
+  const obj = asRecord(value, "codegen schema");
+  assertString(obj.version, "codegen.version");
+  assertNumber(obj.generated_at_unix, "codegen.generated_at_unix");
+  const host = asRecord(obj.host, "codegen.host");
+  assertString(host.id, "codegen.host.id");
+  assertString(host.endpoint, "codegen.host.endpoint");
+  assertString(host.protocol, "codegen.host.protocol");
+  const runtime = asRecord(obj.runtime, "codegen.runtime");
+  if (!("invoke_options_schema" in runtime)) {
+    throw new Error("Invalid codegen schema: runtime.invoke_options_schema is required");
+  }
+  if (!("result_meta_schema" in runtime)) {
+    throw new Error("Invalid codegen schema: runtime.result_meta_schema is required");
+  }
+  if (!("artifact_meta_schema" in runtime)) {
+    throw new Error("Invalid codegen schema: runtime.artifact_meta_schema is required");
+  }
+  if (!("lifecycle_contract" in runtime)) {
+    throw new Error("Invalid codegen schema: runtime.lifecycle_contract is required");
+  }
+  if (!("artifact_contract" in runtime)) {
+    throw new Error("Invalid codegen schema: runtime.artifact_contract is required");
+  }
+  if (!Array.isArray(obj.operations)) {
+    throw new Error("Invalid codegen schema: operations must be an array");
+  }
+  for (const [index, operationValue] of obj.operations.entries()) {
+    const operation = asRecord(operationValue, `codegen.operations[${index}]`);
+    assertString(operation.id, `codegen.operations[${index}].id`);
+    assertString(operation.display_name, `codegen.operations[${index}].display_name`);
+    assertString(operation.kind, `codegen.operations[${index}].kind`);
+    assertString(operation.result_kind, `codegen.operations[${index}].result_kind`);
+    assertBoolean(operation.execute, `codegen.operations[${index}].execute`);
+    assertBoolean(operation.help_only, `codegen.operations[${index}].help_only`);
+    assertBoolean(operation.subscribable, `codegen.operations[${index}].subscribable`);
+  }
+}
+function asRecord(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid ${label}: expected object`);
+  }
+  return value;
+}
+function assertString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Invalid ${label}: expected non-empty string`);
+  }
+}
+function assertNumber(value, label) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`Invalid ${label}: expected number`);
+  }
+}
+function assertBoolean(value, label) {
+  if (typeof value !== "boolean") {
+    throw new Error(`Invalid ${label}: expected boolean`);
+  }
+}
 function normalizeOptions(options) {
   return {
     inject_env: [],
@@ -279,5 +666,6 @@ function tryParseFrame(buffer) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DaemonRpcError,
-  UxcDaemonClient
+  UxcDaemonClient,
+  generateTypeScriptClient
 });

package/dist/index.d.cts

@@ -6,9 +6,13 @@ interface RuntimeInvokeOptions {
     refresh_schema?: boolean;
     schema_url?: string;
     link_name?: string;
+    link_skill?: string;
+    link_skill_doc?: string;
+    link_skill_path?: string;
     schema_mapping_file?: string;
     daemon_exclusive?: string[];
     daemon_idle_ttl?: number;
+    request_headers?: Record<string, string>;
 }
 interface RuntimeInvokeResponse {
     protocol: string;
@@ -17,8 +21,59 @@ interface RuntimeInvokeResponse {
     operation?: string | null;
     data: unknown;
     duration_ms?: number | null;
-    meta: Record<string, unknown>;
+    meta: RuntimeMeta;
 }
+interface RuntimeMeta {
+    schema_involved?: boolean | null;
+    cache_source?: string | null;
+    cache_age_ms?: number | null;
+    cache_stale?: boolean | null;
+    cache_fallback?: boolean | null;
+    daemon_session_reused?: boolean | null;
+    response_status_code?: number | null;
+    response_headers?: Record<string, string> | null;
+    artifact_truncated?: boolean | null;
+    artifact_kind?: string | null;
+    artifact_bytes?: number | null;
+    artifact_path?: string | null;
+    artifact_ref?: string | null;
+    artifact_sha256?: string | null;
+    [key: string]: unknown;
+}
+interface CodegenHostSchemaV1 {
+    version: "v1" | string;
+    generated_at_unix: number;
+    host: {
+        id: string;
+        endpoint: string;
+        protocol: string;
+        link_name?: string | null;
+    };
+    runtime: {
+        invoke_options_schema: unknown;
+        result_meta_schema: unknown;
+        artifact_meta_schema: unknown;
+        lifecycle_contract: unknown;
+        artifact_contract: unknown;
+    };
+    operations: CodegenOperationV1[];
+}
+interface CodegenOperationV1 {
+    id: string;
+    display_name: string;
+    description?: string | null;
+    kind: string;
+    input_schema?: unknown;
+    output_schema?: unknown;
+    result_kind: string;
+    execute: boolean;
+    help_only: boolean;
+    subscribable: boolean;
+}
+type RuntimeResult<TData = unknown, TMeta = Record<string, unknown>> = Omit<RuntimeInvokeResponse, "data" | "meta"> & {
+    data: TData;
+    meta: TMeta;
+};
 interface SubscriptionEventEnvelope {
     version: string;
     job_id: string;
@@ -92,18 +147,48 @@ interface UxcDaemonClientOptions {
     requestTimeoutMs?: number;
     env?: NodeJS.ProcessEnv;
 }
+interface GenerateTypeScriptClientOptions {
+    className?: string;
+    packageImport?: string;
+    includeSchemaJson?: boolean;
+}
 interface SubscribeStartArgs {
     endpoint: string;
     resourceUri?: string;
     operationId?: string;
     args?: Record<string, unknown>;
     mode?: "stream" | "poll";
+    pollConfig?: PollSubscriptionConfig;
     options?: RuntimeInvokeOptions;
     sink?: `file:${string}` | "memory:";
     ephemeral?: boolean;
     readResource?: boolean;
     transportHint?: "websocket" | "discord_gateway" | "slack_socket_mode" | "feishu_long_connection";
 }
+interface PollSubscriptionConfig {
+    interval_secs: number;
+    extract_items_pointer: string;
+    missing_extract_items_pointer_as_empty?: boolean;
+    request_cursor_arg?: string;
+    response_cursor_pointer?: string;
+    cursor_from_item_pointer?: string;
+    cursor_transform?: "increment";
+    checkpoint_strategy: {
+        type: "cursor_only";
+    } | {
+        type: "item_key";
+        item_key_pointer: string;
+        seen_window?: number;
+    } | {
+        type: "watermark";
+        item_watermark_pointer: string;
+        item_tiebreaker_pointer?: string;
+        seen_window?: number;
+    } | {
+        type: "content_hash";
+        seen_window?: number;
+    };
+}
 declare class DaemonRpcError extends Error {
     readonly code: number;
     readonly method: string;
@@ -123,9 +208,18 @@ declare class UxcDaemonClient {
     call(args: {
         endpoint: string;
         operation: string;
-        payload?: Record<string, unknown>;
+        payload?: Record<string, unknown> | undefined;
         options?: RuntimeInvokeOptions;
     }): Promise<RuntimeInvokeResponse>;
+    codegenSchema(args: {
+        endpoint: string;
+        options?: RuntimeInvokeOptions;
+    }): Promise<CodegenHostSchemaV1>;
+    generateTypeScriptClient(args: {
+        endpoint: string;
+        options?: RuntimeInvokeOptions;
+        emitter?: GenerateTypeScriptClientOptions;
+    }): Promise<string>;
     subscribeStart(args: SubscribeStartArgs): Promise<SubscribeStartResponse>;
     subscribeList(): Promise<SubscriptionJobView[]>;
     subscribeStatus(jobId: string): Promise<SubscriptionJobView>;
@@ -146,5 +240,6 @@ declare class UxcDaemonClient {
     private ensureDaemon;
     private requestOnce;
 }
+declare function generateTypeScriptClient(schema: CodegenHostSchemaV1, options?: GenerateTypeScriptClientOptions): string;
 
-export { DaemonRpcError, type DaemonStatus, type RuntimeInvokeOptions, type RuntimeInvokeResponse, type SubscribeStartArgs, type SubscribeStartResponse, type SubscribeStopResponse, type SubscriptionEventEnvelope, type SubscriptionEventsResponse, type SubscriptionJobView, UxcDaemonClient, type UxcDaemonClientOptions };
+export { type CodegenHostSchemaV1, type CodegenOperationV1, DaemonRpcError, type DaemonStatus, type GenerateTypeScriptClientOptions, type PollSubscriptionConfig, type RuntimeInvokeOptions, type RuntimeInvokeResponse, type RuntimeMeta, type RuntimeResult, type SubscribeStartArgs, type SubscribeStartResponse, type SubscribeStopResponse, type SubscriptionEventEnvelope, type SubscriptionEventsResponse, type SubscriptionJobView, UxcDaemonClient, type UxcDaemonClientOptions, generateTypeScriptClient };

package/dist/index.d.ts

@@ -6,9 +6,13 @@ interface RuntimeInvokeOptions {
     refresh_schema?: boolean;
     schema_url?: string;
     link_name?: string;
+    link_skill?: string;
+    link_skill_doc?: string;
+    link_skill_path?: string;
     schema_mapping_file?: string;
     daemon_exclusive?: string[];
     daemon_idle_ttl?: number;
+    request_headers?: Record<string, string>;
 }
 interface RuntimeInvokeResponse {
     protocol: string;
@@ -17,8 +21,59 @@ interface RuntimeInvokeResponse {
     operation?: string | null;
     data: unknown;
     duration_ms?: number | null;
-    meta: Record<string, unknown>;
+    meta: RuntimeMeta;
 }
+interface RuntimeMeta {
+    schema_involved?: boolean | null;
+    cache_source?: string | null;
+    cache_age_ms?: number | null;
+    cache_stale?: boolean | null;
+    cache_fallback?: boolean | null;
+    daemon_session_reused?: boolean | null;
+    response_status_code?: number | null;
+    response_headers?: Record<string, string> | null;
+    artifact_truncated?: boolean | null;
+    artifact_kind?: string | null;
+    artifact_bytes?: number | null;
+    artifact_path?: string | null;
+    artifact_ref?: string | null;
+    artifact_sha256?: string | null;
+    [key: string]: unknown;
+}
+interface CodegenHostSchemaV1 {
+    version: "v1" | string;
+    generated_at_unix: number;
+    host: {
+        id: string;
+        endpoint: string;
+        protocol: string;
+        link_name?: string | null;
+    };
+    runtime: {
+        invoke_options_schema: unknown;
+        result_meta_schema: unknown;
+        artifact_meta_schema: unknown;
+        lifecycle_contract: unknown;
+        artifact_contract: unknown;
+    };
+    operations: CodegenOperationV1[];
+}
+interface CodegenOperationV1 {
+    id: string;
+    display_name: string;
+    description?: string | null;
+    kind: string;
+    input_schema?: unknown;
+    output_schema?: unknown;
+    result_kind: string;
+    execute: boolean;
+    help_only: boolean;
+    subscribable: boolean;
+}
+type RuntimeResult<TData = unknown, TMeta = Record<string, unknown>> = Omit<RuntimeInvokeResponse, "data" | "meta"> & {
+    data: TData;
+    meta: TMeta;
+};
 interface SubscriptionEventEnvelope {
     version: string;
     job_id: string;
@@ -92,18 +147,48 @@ interface UxcDaemonClientOptions {
     requestTimeoutMs?: number;
     env?: NodeJS.ProcessEnv;
 }
+interface GenerateTypeScriptClientOptions {
+    className?: string;
+    packageImport?: string;
+    includeSchemaJson?: boolean;
+}
 interface SubscribeStartArgs {
     endpoint: string;
     resourceUri?: string;
     operationId?: string;
     args?: Record<string, unknown>;
     mode?: "stream" | "poll";
+    pollConfig?: PollSubscriptionConfig;
     options?: RuntimeInvokeOptions;
     sink?: `file:${string}` | "memory:";
     ephemeral?: boolean;
     readResource?: boolean;
     transportHint?: "websocket" | "discord_gateway" | "slack_socket_mode" | "feishu_long_connection";
 }
+interface PollSubscriptionConfig {
+    interval_secs: number;
+    extract_items_pointer: string;
+    missing_extract_items_pointer_as_empty?: boolean;
+    request_cursor_arg?: string;
+    response_cursor_pointer?: string;
+    cursor_from_item_pointer?: string;
+    cursor_transform?: "increment";
+    checkpoint_strategy: {
+        type: "cursor_only";
+    } | {
+        type: "item_key";
+        item_key_pointer: string;
+        seen_window?: number;
+    } | {
+        type: "watermark";
+        item_watermark_pointer: string;
+        item_tiebreaker_pointer?: string;
+        seen_window?: number;
+    } | {
+        type: "content_hash";
+        seen_window?: number;
+    };
+}
 declare class DaemonRpcError extends Error {
     readonly code: number;
     readonly method: string;
@@ -123,9 +208,18 @@ declare class UxcDaemonClient {
     call(args: {
         endpoint: string;
         operation: string;
-        payload?: Record<string, unknown>;
+        payload?: Record<string, unknown> | undefined;
         options?: RuntimeInvokeOptions;
     }): Promise<RuntimeInvokeResponse>;
+    codegenSchema(args: {
+        endpoint: string;
+        options?: RuntimeInvokeOptions;
+    }): Promise<CodegenHostSchemaV1>;
+    generateTypeScriptClient(args: {
+        endpoint: string;
+        options?: RuntimeInvokeOptions;
+        emitter?: GenerateTypeScriptClientOptions;
+    }): Promise<string>;
     subscribeStart(args: SubscribeStartArgs): Promise<SubscribeStartResponse>;
     subscribeList(): Promise<SubscriptionJobView[]>;
     subscribeStatus(jobId: string): Promise<SubscriptionJobView>;
@@ -146,5 +240,6 @@ declare class UxcDaemonClient {
     private ensureDaemon;
     private requestOnce;
 }
+declare function generateTypeScriptClient(schema: CodegenHostSchemaV1, options?: GenerateTypeScriptClientOptions): string;
 
-export { DaemonRpcError, type DaemonStatus, type RuntimeInvokeOptions, type RuntimeInvokeResponse, type SubscribeStartArgs, type SubscribeStartResponse, type SubscribeStopResponse, type SubscriptionEventEnvelope, type SubscriptionEventsResponse, type SubscriptionJobView, UxcDaemonClient, type UxcDaemonClientOptions };
+export { type CodegenHostSchemaV1, type CodegenOperationV1, DaemonRpcError, type DaemonStatus, type GenerateTypeScriptClientOptions, type PollSubscriptionConfig, type RuntimeInvokeOptions, type RuntimeInvokeResponse, type RuntimeMeta, type RuntimeResult, type SubscribeStartArgs, type SubscribeStartResponse, type SubscribeStopResponse, type SubscriptionEventEnvelope, type SubscriptionEventsResponse, type SubscriptionJobView, UxcDaemonClient, type UxcDaemonClientOptions, generateTypeScriptClient };

package/dist/index.js

@@ -47,7 +47,38 @@ var UxcDaemonClient = class {
       options: normalizeOptions(args.options)
     });
   }
+  async codegenSchema(args) {
+    const response = await this.request("runtime.invoke", {
+      request_id: requestId("codegen"),
+      endpoint: args.endpoint,
+      action: "codegen_schema",
+      operation_id: null,
+      args: null,
+      options: normalizeOptions(args.options)
+    });
+    if (response.kind !== "codegen_host_schema") {
+      throw new Error(
+        `Unexpected codegen response kind '${response.kind}' (expected codegen_host_schema)`
+      );
+    }
+    assertCodegenHostSchema(response.data);
+    return response.data;
+  }
+  async generateTypeScriptClient(args) {
+    const schema = await this.codegenSchema({
+      endpoint: args.endpoint,
+      options: args.options
+    });
+    return generateTypeScriptClient(schema, args.emitter);
+  }
   async subscribeStart(args) {
+    const mode = args.mode ?? (args.pollConfig ? "poll" : "stream");
+    if (mode === "poll" && !args.pollConfig) {
+      throw new Error("pollConfig is required when mode is 'poll'");
+    }
+    if (mode !== "poll" && args.pollConfig) {
+      throw new Error("pollConfig is only valid when mode is 'poll'");
+    }
     return this.request("subscription.start", {
       request_id: requestId("subscribe"),
       endpoint: args.endpoint,
@@ -59,8 +90,8 @@ var UxcDaemonClient = class {
       transport_hint: args.transportHint ?? null,
       subprotocols: [],
       initial_text_frames: [],
-      mode: args.mode ?? "stream",
-      poll_config: null,
+      mode,
+      poll_config: args.pollConfig ?? null,
       ephemeral: args.ephemeral ?? (args.sink ?? "memory:") === "memory:",
       options: normalizeOptions(args.options)
     });
@@ -194,6 +225,361 @@ var UxcDaemonClient = class {
     return response;
   }
 };
+function generateTypeScriptClient(schema, options = {}) {
+  const packageImport = options.packageImport ?? "@holon-run/uxc-daemon-client";
+  const className = sanitizeTypeName(options.className ?? defaultClassName(schema.host.id));
+  const methodNames = /* @__PURE__ */ new Set();
+  const typeNames = /* @__PURE__ */ new Set();
+  const operationBlocks = [];
+  const typeBlocks = [];
+  for (const operation of schema.operations) {
+    if (!operation.execute || operation.help_only || operation.subscribable) {
+      continue;
+    }
+    const methodName = uniqueName(
+      sanitizeMethodName(defaultMethodName(operation.id)),
+      methodNames
+    );
+    const typeName = uniqueName(
+      sanitizeTypeName(`${upperFirst(methodName)}Input`),
+      typeNames
+    );
+    const selectedInputSchema = selectOperationInputSchema(operation.input_schema);
+    const inputType = selectedInputSchema ? renderTsTypeFromSchema(selectedInputSchema, 0) : "Record<string, unknown>";
+    const inputRequired = selectedInputSchema ? hasRequiredInput(selectedInputSchema) : false;
+    typeBlocks.push(`export type ${typeName} = ${inputType};`);
+    operationBlocks.push(
+      [
+        `  async ${methodName}(`,
+        inputRequired ? `    input: ${typeName},` : `    input?: ${typeName},`,
+        `    options: RuntimeInvokeOptions = {},`,
+        `  ): Promise<RuntimeResult<unknown>> {`,
+        `    return this.client.call({`,
+        `      endpoint: this.endpoint,`,
+        `      operation: ${JSON.stringify(operation.id)},`,
+        `      payload: toRuntimePayload(input),`,
+        `      options: { ...this.defaultOptions, ...options },`,
+        `    }) as Promise<RuntimeResult<unknown>>;`,
+        `  }`
+      ].join("\n")
+    );
+  }
+  const lines = [
+    `import { UxcDaemonClient, type RuntimeInvokeOptions, type RuntimeResult } from ${JSON.stringify(packageImport)};`,
+    "",
+    ...typeBlocks,
+    "",
+    `export interface ${className}Options {`,
+    "  client?: UxcDaemonClient;",
+    "  endpoint?: string;",
+    "  defaultOptions?: RuntimeInvokeOptions;",
+    "}",
+    "",
+    `export class ${className} {`,
+    "  readonly client: UxcDaemonClient;",
+    "  readonly endpoint: string;",
+    "  readonly defaultOptions: RuntimeInvokeOptions;",
+    "",
+    `  constructor(options: ${className}Options = {}) {`,
+    "    this.client = options.client ?? new UxcDaemonClient();",
+    `    this.endpoint = options.endpoint ?? ${JSON.stringify(schema.host.endpoint)};`,
+    "    this.defaultOptions = options.defaultOptions ?? {};",
+    "  }",
+    "",
+    ...operationBlocks,
+    "}",
+    "",
+    "function toRuntimePayload(input: unknown): Record<string, unknown> | undefined {",
+    "  if (input == null) {",
+    "    return undefined;",
+    "  }",
+    '  if (typeof input === "object" && !Array.isArray(input)) {',
+    "    return input as Record<string, unknown>;",
+    "  }",
+    "  return { body: input };",
+    "}"
+  ];
+  if (options.includeSchemaJson) {
+    lines.push(
+      "",
+      `export const GENERATED_SCHEMA = ${JSON.stringify(schema, null, 2)} as const;`
+    );
+  }
+  return `${lines.join("\n")}
+`;
+}
+function defaultClassName(hostId) {
+  return `${sanitizeTypeName(hostId)}Client`;
+}
+function defaultMethodName(operationId) {
+  const openApiMatch = operationId.match(/^([a-z]+):\/(.*)$/i);
+  if (openApiMatch) {
+    const verb = openApiMatch[1].toLowerCase();
+    const path = openApiMatch[2].replace(/\{([^}]+)\}/g, " by $1 ").replace(/[/:_-]+/g, " ");
+    return `${verb} ${path}`;
+  }
+  return operationId.replace(/[/:._-]+/g, " ");
+}
+function sanitizeMethodName(raw) {
+  const tokens = raw.replace(/[^a-zA-Z0-9]+/g, " ").trim().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) {
+    return "invoke";
+  }
+  const [first, ...rest] = tokens;
+  const normalized = [first.toLowerCase(), ...rest.map((token) => upperFirst(token.toLowerCase()))].join(
+    ""
+  );
+  return /^[a-zA-Z_$]/.test(normalized) ? normalized : `op${upperFirst(normalized)}`;
+}
+function sanitizeTypeName(raw) {
+  if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(raw)) {
+    return raw;
+  }
+  const tokens = raw.replace(/[^a-zA-Z0-9]+/g, " ").trim().split(/\s+/).filter(Boolean).map((token) => upperFirst(token));
+  const candidate = tokens.join("") || "Generated";
+  return /^[A-Za-z_$]/.test(candidate) ? candidate : `T${candidate}`;
+}
+function upperFirst(input) {
+  if (input.length === 0) {
+    return input;
+  }
+  return `${input[0].toUpperCase()}${input.slice(1)}`;
+}
+function uniqueName(name, used) {
+  let candidate = name;
+  let idx = 2;
+  while (used.has(candidate)) {
+    candidate = `${name}${idx}`;
+    idx += 1;
+  }
+  used.add(candidate);
+  return candidate;
+}
+function hasRequiredInput(schema) {
+  if (!schema || typeof schema !== "object") {
+    return false;
+  }
+  const required = schema.required;
+  return Array.isArray(required) && required.length > 0;
+}
+function selectOperationInputSchema(inputSchema) {
+  if (!inputSchema || typeof inputSchema !== "object") {
+    return void 0;
+  }
+  const obj = inputSchema;
+  if (obj.kind === "grpc_message" && typeof obj.schema === "object") {
+    return obj.schema;
+  }
+  if (obj.kind === "openrpc_method" && Array.isArray(obj.params)) {
+    const properties = {};
+    const required = [];
+    for (const raw of obj.params) {
+      if (!raw || typeof raw !== "object") {
+        continue;
+      }
+      const param = raw;
+      const name = typeof param.name === "string" ? param.name : void 0;
+      if (!name) {
+        continue;
+      }
+      const schema = typeof param.schema === "object" ? param.schema : {};
+      properties[name] = schema;
+      if (param.required === true) {
+        required.push(name);
+      }
+    }
+    return { type: "object", properties, required };
+  }
+  if (obj.kind === "openapi_request_body" && obj.content && typeof obj.content === "object") {
+    const content = obj.content;
+    const prioritized = [
+      "application/json",
+      "application/x-www-form-urlencoded",
+      "multipart/form-data"
+    ];
+    for (const mime of prioritized) {
+      const entry = content[mime];
+      if (entry && typeof entry === "object" && entry.schema) {
+        return entry.schema;
+      }
+    }
+    for (const entry of Object.values(content)) {
+      if (entry && typeof entry === "object" && entry.schema) {
+        return entry.schema;
+      }
+    }
+  }
+  if (typeof obj.schema === "object" && obj.type == null) {
+    return obj.schema;
+  }
+  return inputSchema;
+}
+function renderTsTypeFromSchema(schema, depth) {
+  if (!schema || typeof schema !== "object") {
+    return "Record<string, unknown>";
+  }
+  const obj = schema;
+  const typeInfo = resolveSchemaType(obj.type);
+  const enumValues = asPrimitiveArray(obj.enum);
+  if (enumValues && enumValues.length > 0) {
+    return withNullable(
+      enumValues.map((value) => JSON.stringify(value)).join(" | "),
+      typeInfo.nullable
+    );
+  }
+  if (Array.isArray(obj.oneOf) && obj.oneOf.length > 0) {
+    return withNullable(
+      obj.oneOf.map((item) => renderTsTypeFromSchema(item, depth + 1)).join(" | "),
+      typeInfo.nullable
+    );
+  }
+  if (Array.isArray(obj.anyOf) && obj.anyOf.length > 0) {
+    return withNullable(
+      obj.anyOf.map((item) => renderTsTypeFromSchema(item, depth + 1)).join(" | "),
+      typeInfo.nullable
+    );
+  }
+  const schemaType = typeInfo.base;
+  const openApiNullable = obj.nullable === true;
+  switch (schemaType) {
+    case "string":
+      return withNullable("string", typeInfo.nullable || openApiNullable);
+    case "integer":
+    case "number":
+      return withNullable("number", typeInfo.nullable || openApiNullable);
+    case "boolean":
+      return withNullable("boolean", typeInfo.nullable || openApiNullable);
+    case "null":
+      return "null";
+    case "array": {
+      const itemType = renderTsTypeFromSchema(obj.items, depth + 1);
+      return withNullable(`Array<${itemType}>`, typeInfo.nullable || openApiNullable);
+    }
+    case "object": {
+      const properties = obj.properties;
+      if (!properties || typeof properties !== "object") {
+        return withNullable("Record<string, unknown>", typeInfo.nullable || openApiNullable);
+      }
+      if (depth > 4) {
+        return withNullable("Record<string, unknown>", typeInfo.nullable || openApiNullable);
+      }
+      const required = new Set(
+        Array.isArray(obj.required) ? obj.required.filter((item) => typeof item === "string") : []
+      );
+      const fields = Object.entries(properties).map(([name, value]) => {
+        const optional = required.has(name) ? "" : "?";
+        const key = safePropertyName(name);
+        const valueType = renderTsTypeFromSchema(value, depth + 1);
+        return `${key}${optional}: ${valueType}`;
+      });
+      if (fields.length === 0) {
+        return withNullable("Record<string, unknown>", typeInfo.nullable || openApiNullable);
+      }
+      return withNullable(`{ ${fields.join("; ")} }`, typeInfo.nullable || openApiNullable);
+    }
+    default:
+      return withNullable("unknown", typeInfo.nullable || openApiNullable);
+  }
+}
+function resolveSchemaType(typeValue) {
+  if (typeof typeValue === "string") {
+    return {
+      base: typeValue,
+      nullable: typeValue === "null"
+    };
+  }
+  if (Array.isArray(typeValue)) {
+    const nullable = typeValue.some((entry) => entry === "null");
+    const nonNull = typeValue.find(
+      (entry) => typeof entry === "string" && entry !== "null"
+    );
+    return {
+      base: nonNull,
+      nullable
+    };
+  }
+  return {
+    base: void 0,
+    nullable: false
+  };
+}
+function asPrimitiveArray(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const allPrimitive = value.every(
+    (item) => item == null || typeof item === "string" || typeof item === "number" || typeof item === "boolean"
+  );
+  return allPrimitive ? value : void 0;
+}
+function safePropertyName(name) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+function withNullable(type, nullable) {
+  if (!nullable || type.includes("null")) {
+    return type;
+  }
+  return `${type} | null`;
+}
+function assertCodegenHostSchema(value) {
+  const obj = asRecord(value, "codegen schema");
+  assertString(obj.version, "codegen.version");
+  assertNumber(obj.generated_at_unix, "codegen.generated_at_unix");
+  const host = asRecord(obj.host, "codegen.host");
+  assertString(host.id, "codegen.host.id");
+  assertString(host.endpoint, "codegen.host.endpoint");
+  assertString(host.protocol, "codegen.host.protocol");
+  const runtime = asRecord(obj.runtime, "codegen.runtime");
+  if (!("invoke_options_schema" in runtime)) {
+    throw new Error("Invalid codegen schema: runtime.invoke_options_schema is required");
+  }
+  if (!("result_meta_schema" in runtime)) {
+    throw new Error("Invalid codegen schema: runtime.result_meta_schema is required");
+  }
+  if (!("artifact_meta_schema" in runtime)) {
+    throw new Error("Invalid codegen schema: runtime.artifact_meta_schema is required");
+  }
+  if (!("lifecycle_contract" in runtime)) {
+    throw new Error("Invalid codegen schema: runtime.lifecycle_contract is required");
+  }
+  if (!("artifact_contract" in runtime)) {
+    throw new Error("Invalid codegen schema: runtime.artifact_contract is required");
+  }
+  if (!Array.isArray(obj.operations)) {
+    throw new Error("Invalid codegen schema: operations must be an array");
+  }
+  for (const [index, operationValue] of obj.operations.entries()) {
+    const operation = asRecord(operationValue, `codegen.operations[${index}]`);
+    assertString(operation.id, `codegen.operations[${index}].id`);
+    assertString(operation.display_name, `codegen.operations[${index}].display_name`);
+    assertString(operation.kind, `codegen.operations[${index}].kind`);
+    assertString(operation.result_kind, `codegen.operations[${index}].result_kind`);
+    assertBoolean(operation.execute, `codegen.operations[${index}].execute`);
+    assertBoolean(operation.help_only, `codegen.operations[${index}].help_only`);
+    assertBoolean(operation.subscribable, `codegen.operations[${index}].subscribable`);
+  }
+}
+function asRecord(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid ${label}: expected object`);
+  }
+  return value;
+}
+function assertString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Invalid ${label}: expected non-empty string`);
+  }
+}
+function assertNumber(value, label) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`Invalid ${label}: expected number`);
+  }
+}
+function assertBoolean(value, label) {
+  if (typeof value !== "boolean") {
+    throw new Error(`Invalid ${label}: expected boolean`);
+  }
+}
 function normalizeOptions(options) {
   return {
     inject_env: [],
@@ -243,5 +629,6 @@ function tryParseFrame(buffer) {
 }
 export {
   DaemonRpcError,
-  UxcDaemonClient
+  UxcDaemonClient,
+  generateTypeScriptClient
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/uxc-daemon-client",
-  "version": "0.12.8",
+  "version": "0.13.3",
   "description": "Thin Node.js client for UXC daemon-backed operations",
   "license": "MIT",
   "repository": {