@inhuman.tools/harness-contract 0.0.0-stage → 0.1.0

package/src/schemas/shapes.ts

@@ -0,0 +1,379 @@
+import { z } from "zod";
+
+import { uiFormSchema } from "./rpc.js";
+
+/**
+ * Mirrors `REASONING_EFFORTS` in `@inhuman.tools/plugin-sdk`. Inlined so this
+ * package stays dependency-light; harness has a test that the two lists match.
+ */
+export const REASONING_EFFORTS = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+const nonempty = z.string().trim().min(1);
+
+/** Access to one already-running MCP server, by the server's name. */
+export const botMcpGrantSchema = z.strictObject({
+  server: nonempty,
+  tools: z.array(nonempty).optional(),
+  account: nonempty.optional(),
+  session: nonempty.optional(),
+});
+
+export type BotMcpGrant = z.infer<typeof botMcpGrantSchema>;
+
+export const kvScopeSchema = z.enum(["session", "project", "kernel"]).default("session");
+
+export const kvSetInput = z.object({
+  key: z.string().trim().min(1, "key is required"),
+  value: z.string(),
+  scope: kvScopeSchema,
+  /**
+   * Session `model` / `connection` also become the last-choice default
+   * (project + kernel). `/model` and `/connect` send "1". Scheme #t does
+   * not survive the action JSON walk. A bare session write — subagent,
+   * `--model`, `--connection` — does not.
+   */
+  remember: z
+    .union([z.boolean(), z.literal("1")])
+    .optional()
+    .transform((value) => value === true || value === "1"),
+});
+export const kvClearInput = z.object({
+  key: z.string().trim().min(1, "key is required"),
+  scope: kvScopeSchema,
+});
+export const kvOutput = z.object({ ok: z.literal(true) });
+
+/**
+ * A plugin command's call into that plugin's own state. `args` is a JSON
+ * object, since action params cross as strings. `field` names the argument
+ * the composer text (`input`) fills; an empty `input` then refuses.
+ */
+export const pluginMethodInput = z.object({
+  plugin: z.string().trim().min(1, "plugin is required"),
+  method: z.string().trim().min(1, "method is required"),
+  scope: z.enum(["session", "project", "global"]).default("session"),
+  args: z.string().optional(),
+  field: z.string().trim().optional(),
+  input: z.string().optional(),
+});
+/** A failure is data, so a command body that reads state still renders; the TUI shows `error` for a fired action. */
+export const pluginMethodOutput = z.union([
+  z.object({ ok: z.literal(true), value: z.unknown() }),
+  z.object({ ok: z.literal(false), error: z.string() }),
+]);
+
+export const policySetInput = z.object({
+  policy: z.enum(["manual", "auto", "yolo"]),
+});
+export const policySetOutput = z.object({ ok: z.literal(true) });
+
+export const termContinueSetInput = z.object({
+  key: z.string().trim().min(1, "key is required"),
+  sessionId: z.string().trim().min(1, "sessionId is required"),
+});
+export const termContinueClearInput = z.object({
+  key: z.string().trim().min(1, "key is required"),
+});
+export const termContinueOutput = z.object({ ok: z.literal(true) });
+
+/** One picture on a `turn`. Bytes are standard base64. The daemon stores them beside the session. */
+export const turnVisualInput = z.object({
+  mime: z.string().trim().min(1),
+  bytesBase64: z.string().trim().min(1).max(7_000_000),
+  sourcePath: z.string().optional(),
+});
+
+export const turnInput = z.object({
+  prompt: z.string(),
+  kind: z.enum(["steer", "queue", "continue"]).optional(),
+  visuals: z.array(turnVisualInput).max(8).optional(),
+});
+export const turnOutput = z.object({ ok: z.literal(true) });
+
+export const turnVisualReadInput = z.object({
+  id: z.string().trim().min(1),
+});
+export const turnVisualReadOutput = z.object({
+  id: z.string(),
+  mime: z.string(),
+  bytesBase64: z.string(),
+  width: z.number(),
+  height: z.number(),
+  resizedFrom: z.object({ width: z.number(), height: z.number() }).nullable(),
+  sourcePath: z.string().nullable(),
+});
+
+/** A blob the session's document references by content hash (`StoredBlob.sha256`). */
+export const blobGetInput = z.object({
+  sha256: z.string().regex(/^[0-9a-f]{64}$/),
+});
+/** `text` for `text/*` media types, `bytesBase64` for everything else; exactly one is non-null. */
+export const blobGetOutput = z.object({
+  sha256: z.string(),
+  bytes: z.number().int().min(0),
+  mime: z.string(),
+  text: z.string().nullable(),
+  bytesBase64: z.string().nullable(),
+});
+
+/** `dryRun` counts what would move and writes nothing. */
+export const blobVacuumInput = z.object({
+  dryRun: z.boolean().optional(),
+});
+/** What moved (or, on a dry run, would): entities by seat, the UTF-8 bytes taken out of the document, and the stored image's size either side. */
+export const blobVacuumOutput = z.object({
+  dryRun: z.boolean(),
+  fileMutates: z.number().int().min(0),
+  promptMessages: z.number().int().min(0),
+  promptTexts: z.number().int().min(0),
+  bytesMoved: z.number().int().min(0),
+  imageBytesBefore: z.number().int().min(0),
+  imageBytesAfter: z.number().int().min(0),
+});
+
+export const connectAdoptInput = z.object({
+  driver: z.union([
+    z.string().trim().min(1),
+    z.object({ name: z.string().trim().min(1) }).transform((row) => row.name),
+  ]),
+  name: z.string().optional(),
+  settings: z.record(z.string(), z.unknown()).optional(),
+  secrets: z.record(z.string(), z.string()).optional(),
+});
+export const connectAdoptOutput = z.union([z.object({ id: z.string() }), z.object({ ok: z.literal(false) })]);
+export const sessionConnectAdoptOutput = z.union([connectAdoptOutput, uiFormSchema]);
+export const connectDropInput = z.object({
+  id: z.string().trim().min(1, "id is required"),
+  confirm: z.boolean().optional(),
+});
+export const connectDropOutput = z.object({ ok: z.boolean() });
+
+export const mcpServerAdoptInput = z.object({
+  name: z.string().optional(),
+  input: z.string().optional(),
+  settings: z.record(z.string(), z.unknown()).optional(),
+  secrets: z.record(z.string(), z.string()).optional(),
+});
+export const mcpServerAdoptOutput = connectAdoptOutput;
+
+export const mcpServerSearchInput = z.object({
+  query: z.string().trim().min(1, "query is required"),
+  limit: z.number().int().min(1).max(20).optional(),
+});
+export const mcpServerSearchHit = z.object({
+  name: z.string(),
+  title: z.string(),
+  description: z.string(),
+  install: z.string(),
+});
+export const mcpServerSearchOutput = z.object({
+  servers: z.array(mcpServerSearchHit),
+});
+
+export const pluginSetInput = z
+  .object({
+    name: z.string().trim().min(1, "name is required"),
+    enabled: z.boolean().optional(),
+    foreground: z.boolean().optional(),
+  })
+  .refine((row) => row.enabled !== undefined || row.foreground !== undefined, {
+    message: "enabled or foreground is required",
+  });
+export const pluginSetOutput = z.object({ ok: z.literal(true) });
+
+export const pluginInstallInput = z.object({
+  spec: z.string().trim().min(1, "spec is required"),
+});
+export const pluginInstallOutput = z.object({
+  name: z.string(),
+  npmName: z.string(),
+});
+export const pluginRemoveInput = z.object({
+  name: z.string().trim().min(1, "name is required"),
+});
+export const pluginRemoveOutput = z.object({ ok: z.literal(true) });
+
+/** Rename or merge settings of a connection that already exists. The id stays. */
+export const connectUpdateInput = z
+  .object({
+    id: z.string().trim().min(1, "id is required"),
+    name: z.string().trim().min(1).optional(),
+    settings: z.record(z.string(), z.unknown()).optional(),
+  })
+  .refine((row) => row.name !== undefined || row.settings !== undefined, {
+    message: "name or settings is required",
+  });
+export const connectUpdateOutput = z.object({ ok: z.literal(true) });
+
+export const configSetInput = z.object({
+  compact: z.string().optional(),
+  compactKeepTurns: z.number().int().positive().optional(),
+  compactTriggers: z.object({ hard: z.string().optional(), soft: z.string().optional() }).optional(),
+  contextGlowRemaining: z.string().optional(),
+  autoModeClassifier: z.string().optional(),
+  defaultPermissionMode: z.enum(["manual", "auto", "yolo"]).optional(),
+  approvalAskThrottleMs: z.number().finite().nonnegative().optional(),
+  shellTailBytes: z.number().finite().nonnegative().optional(),
+  superKey: z.enum(["ctrl", "cmd"]).optional(),
+  hideFloorTools: z.boolean().optional(),
+  statusline: z.string().optional(),
+  statuslineRefresh: z.string().optional(),
+  speculativePolicyProcessingTools: z.number().finite().nonnegative().optional(),
+  textOnlyContinue: z.boolean().optional(),
+  /** The user layer of the authorization table (validated by the daemon). `null` clears it. */
+  authorization: z.record(z.string(), z.unknown()).nullable().optional(),
+});
+export const configSetOutput = z.object({ ok: z.literal(true) });
+
+const skillScope = z.enum(["project", "home"]);
+export const skillListInput = z.object({
+  project: z.string().optional(),
+});
+export const skillRowSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  location: z.string(),
+  invoke: z.string(),
+  scope: skillScope,
+});
+export const skillListOutput = z.object({ skills: z.array(skillRowSchema) });
+export const skillWriteInput = z.object({
+  scope: skillScope,
+  project: z.string().optional(),
+  name: z.string().trim().min(1, "name is required"),
+  description: z.string().default(""),
+  body: z.string().default(""),
+});
+export const skillWriteOutput = skillRowSchema;
+export const skillRemoveInput = z.object({
+  scope: skillScope,
+  project: z.string().optional(),
+  name: z.string().trim().min(1, "name is required"),
+});
+export const skillRemoveOutput = z.object({ ok: z.literal(true) });
+export const skillReadInput = skillRemoveInput;
+export const skillReadOutput = skillRowSchema.extend({ body: z.string() });
+
+const recipeScope = z.enum(["session", "project", "global"]);
+export const botWriteInput = z.object({
+  scope: z.enum(["home", "project"]),
+  project: z.string().optional(),
+  name: z.string().trim().min(1, "name is required"),
+  description: z.string().default(""),
+  instructions: z.string().default(""),
+  recipeScope: recipeScope.default("session"),
+  tools: z.array(z.string()).default([]),
+  skills: z.array(z.string()).default([]),
+  keepAlive: z.boolean().default(false),
+  /**
+   * Absent means keep the file's current value. An empty list clears it.
+   * A settings save that does not know these fields must not wipe them.
+   */
+  invokes: z.array(z.string().trim().min(1)).optional(),
+  reasoningEffort: z.enum(REASONING_EFFORTS).nullable().optional(),
+  modelPreferences: z.array(z.string().trim().min(1)).optional(),
+  /** Absent keeps the file's grants. An empty list clears them. */
+  mcp: z.array(botMcpGrantSchema).optional(),
+});
+export const botWriteOutput = z.object({ ok: z.literal(true) });
+export const botRemoveInput = z.object({
+  scope: z.enum(["home", "project"]),
+  project: z.string().optional(),
+  name: z.string().trim().min(1, "name is required"),
+});
+export const botRemoveOutput = z.object({ ok: z.literal(true) });
+
+export const compactInput = z.object({
+  focus: z.string().optional(),
+  from: z.literal("overflow").optional(),
+});
+export const compactOutput = z.union([
+  z.object({ ok: z.literal(true), compacted: z.boolean() }),
+  z.object({ ok: z.literal(false), reason: z.string() }),
+]);
+
+export const renameInput = z.object({
+  title: z.string(),
+});
+export const renameOutput = z.object({
+  ok: z.literal(true),
+  title: z.string(),
+});
+
+export const evalInput = z
+  .object({
+    requestId: z.string().trim().min(1, "requestId is required"),
+    expr: z.string(),
+    source: z.string().optional(),
+    sourcePath: z.string().trim().min(1).optional(),
+    policy: z.string().trim().optional().default("auto"),
+  })
+  .refine((value) => value.source == null || value.sourcePath != null, {
+    message: "source requires sourcePath",
+  });
+export const evalOutput = z.union([
+  z.object({
+    ok: z.literal(true),
+    turnId: z.string(),
+    programId: z.string(),
+  }),
+  z.object({
+    ok: z.literal(false),
+    code: z.literal("policy_unavailable"),
+    text: z.string(),
+  }),
+]);
+
+export const turnCancelInput = z.union([
+  z.object({ turnId: z.string().trim().min(1) }).strict(),
+  z.object({ requestId: z.string().trim().min(1) }).strict(),
+]);
+export const turnCancelOutput = z.object({ ok: z.literal(true) });
+
+export const turnRewindInput = z.object({
+  turnId: z.string().trim().min(1),
+});
+export const turnRewindOutput = z.object({
+  ok: z.literal(true),
+  turnId: z.string(),
+});
+
+export const turnRetryInput = z.object({}).strict();
+export const turnRetryOutput = z.object({ ok: z.literal(true) });
+
+export const residentSetInput = z.object({ resident: z.boolean() });
+export const residentSetOutput = z.object({ ok: z.literal(true) });
+
+/** A queued row named by the id the client saw. Already drained or moved is `ok: false`. */
+export const queueRowInput = z.object({ id: z.string().trim().min(1) });
+export const queueRowOutput = z.object({ ok: z.boolean() });
+
+export const agentCallsListInput = z.object({}).strict();
+export const agentCallsListOutput = z.object({
+  calls: z.array(
+    z.object({
+      requestId: z.string(),
+      callerSessionId: z.string(),
+      tool: z.string(),
+      workerSessionId: z.string(),
+      contributionRevision: z.string(),
+      state: z.enum(["admitted", "accepted", "running", "paused", "terminal"]),
+      blocker: z.string().nullable(),
+      delivery: z.enum(["pending", "delivered"]),
+      outcome: z.unknown().nullable(),
+    }),
+  ),
+});
+
+export const agentCallsInspectInput = z.object({
+  requestId: z.string().trim().min(1),
+});
+export const agentCallsInspectOutput = z.union([
+  agentCallsListOutput.shape.calls.element,
+  z.object({ ok: z.literal(false), reason: z.string() }),
+]);
+
+export const agentCallsCancelInput = z.object({
+  requestId: z.string().trim().min(1),
+});
+export const agentCallsCancelOutput = z.object({ ok: z.boolean() });

package/src/spec/cli.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { generateArtifacts } from "./generate.js";
+
+// dist/spec/cli.js -> packages/harness-contract; the spec lives in its spec/ folder.
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(here, "..", "..");
+const defaultOut = resolve(packageRoot, "spec");
+
+const args = process.argv.slice(2);
+const check = args.includes("--check");
+const outFlag = args.indexOf("--out");
+const out = outFlag === -1 ? defaultOut : resolve(args[outFlag + 1] ?? defaultOut);
+
+const manifest: unknown = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+const version =
+  typeof manifest === "object" && manifest !== null && "version" in manifest && typeof manifest.version === "string"
+    ? manifest.version
+    : "0.0.0";
+
+const artifacts = await generateArtifacts(version);
+
+if (check) {
+  const stale = artifacts.filter((artifact) => {
+    try {
+      return readFileSync(join(out, artifact.file), "utf8") !== artifact.text;
+    } catch {
+      return true;
+    }
+  });
+  if (stale.length > 0) {
+    console.error(
+      `spec/ is stale: ${stale.map((artifact) => artifact.file).join(", ")}. Run: pnpm --filter @inhuman.tools/harness-contract spec`,
+    );
+    process.exit(1);
+  }
+  console.log("spec/ is up to date");
+} else {
+  mkdirSync(out, { recursive: true });
+  for (const artifact of artifacts) writeFileSync(join(out, artifact.file), artifact.text);
+  console.log(`wrote ${artifacts.map((artifact) => artifact.file).join(", ")} to ${out}`);
+}

package/src/spec/generate.ts

@@ -0,0 +1,115 @@
+import { OpenAPIGenerator, type JSONSchema } from "@orpc/openapi";
+import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
+
+import { contract, httpPathOf, listProcedures, type ContractEntry } from "../contract.js";
+import { renderReadme } from "./readme.js";
+
+type Json = Record<string, unknown>;
+type JsonSchemaObject = Exclude<JSONSchema, boolean>;
+
+const converter = new ZodToJsonSchemaConverter();
+
+const INFO = (version: string) => ({
+  title: "inhuman-harness daemon RPC",
+  version,
+});
+
+/**
+ * The OpenAPI view of the contract. This is the HTTP projection (one POST per
+ * method, params as the JSON body); the daemon itself speaks JSON-RPC over a
+ * WebSocket, see `openrpc.json` for the wire-accurate description.
+ */
+export async function generateOpenApi(version: string): Promise<Json> {
+  const generator = new OpenAPIGenerator({ schemaConverters: [converter] });
+  const document = (await generator.generate(contract, {
+    info: {
+      ...INFO(version),
+      description:
+        "HTTP projection of the daemon contract, generated from @inhuman.tools/harness-contract. " +
+        "The daemon's only transport today is JSON-RPC 2.0 over WebSocket (see openrpc.json); each operation here " +
+        "names its wire method in `x-rpc-method`.",
+    },
+  })) as unknown as Json;
+  const byPath = new Map<string, ContractEntry>(listProcedures().map((entry) => [httpPathOf(entry.meta), entry]));
+  const paths = (document.paths ?? {}) as Record<string, Record<string, Json>>;
+  for (const [path, item] of Object.entries(paths)) {
+    const entry = byPath.get(path);
+    const operation = item.post;
+    if (entry === undefined || operation === undefined) continue;
+    operation["x-rpc-method"] = entry.meta.method;
+    operation["x-host"] = entry.meta.host;
+    if (entry.meta.mayPark === true) operation["x-may-park"] = true;
+  }
+  return document;
+}
+
+function schemaOf(schema: ContractEntry["procedure"]["~orpc"]["inputSchema"], strategy: "input" | "output") {
+  const [, json] = converter.convert(schema, { strategy });
+  return json;
+}
+
+function isObjectSchema(schema: JsonSchemaObject): boolean {
+  return schema.type === "object" && schema.anyOf === undefined && schema.oneOf === undefined;
+}
+
+/**
+ * OpenRPC 1.3 description of the wire. Method names come from `meta.method`.
+ * Params are by-name: an object input contributes one param per property; an
+ * input that is not a plain object (a union) is given whole in `x-params-schema`.
+ */
+export async function generateOpenRpc(version: string): Promise<Json> {
+  const methods: Json[] = [];
+  for (const entry of listProcedures()) {
+    const def = entry.procedure["~orpc"];
+    const input = schemaOf(def.inputSchema, "input");
+    const output = schemaOf(def.outputSchema, "output");
+    const tags = def.route.tags?.map((name) => ({ name })) ?? [];
+    const row: Json = {
+      name: entry.meta.method,
+      summary: def.route.summary,
+      ...(def.route.description === undefined ? {} : { description: def.route.description }),
+      tags,
+      paramStructure: "by-name",
+      params: [],
+      result: { name: "result", schema: output },
+      "x-host": entry.meta.host,
+      ...(entry.meta.mayPark === true ? { "x-may-park": true } : {}),
+    };
+    if (typeof input !== "boolean" && isObjectSchema(input)) {
+      const required = new Set(input.required);
+      row.params = Object.entries(input.properties ?? {}).map(([name, schema]) => ({
+        name,
+        required: required.has(name),
+        schema,
+      }));
+    } else {
+      row["x-params-schema"] = input;
+    }
+    methods.push(row);
+  }
+  return {
+    openrpc: "1.3.2",
+    info: {
+      ...INFO(version),
+      description:
+        "JSON-RPC 2.0 over WebSocket text frames on `<root>/daemon.sock`. Generated from @inhuman.tools/harness-contract.",
+    },
+    methods,
+  };
+}
+
+export interface Artifact {
+  readonly file: string;
+  readonly text: string;
+}
+
+const text = (value: unknown): string => `${JSON.stringify(value, null, 2)}\n`;
+
+/** Every generated file, by name relative to the package's `spec/` folder. */
+export async function generateArtifacts(version: string): Promise<Artifact[]> {
+  return [
+    { file: "openapi.json", text: text(await generateOpenApi(version)) },
+    { file: "openrpc.json", text: text(await generateOpenRpc(version)) },
+    { file: "README.md", text: renderReadme(listProcedures()) },
+  ];
+}

package/src/spec/readme.ts

@@ -0,0 +1,126 @@
+import type { ContractEntry } from "../contract.js";
+
+function methodTable(entries: readonly ContractEntry[], host: string): string {
+  const rows = entries
+    .filter((entry) => entry.meta.host === host)
+    .map((entry) => {
+      const summary = entry.procedure["~orpc"].route.summary ?? "";
+      const park = entry.meta.mayPark === true ? "yes" : "";
+      return `| \`${entry.meta.method}\` | \`${entry.path.join(".")}\` | ${park} | ${summary} |`;
+    });
+  return ["| Wire method | Client path | May park | Summary |", "| --- | --- | --- | --- |", ...rows].join("\n");
+}
+
+/** `packages/harness-contract/spec/README.md`. Generated: edit this function, then run the `spec` script. */
+export function renderReadme(entries: readonly ContractEntry[]): string {
+  return `# Daemon RPC
+
+<!-- Generated by \`pnpm --filter @inhuman.tools/harness-contract spec\`. Do not edit by hand. -->
+
+The daemon's RPC surface is declared once, as an oRPC contract, in
+[\`@inhuman.tools/harness-contract\`](../../packages/harness-contract). The
+daemons implement it, [\`@inhuman.tools/harness-client\`](../../packages/harness-client)
+calls it, and the files here are generated from it:
+
+- [\`openrpc.json\`](./openrpc.json): OpenRPC 1.3, wire-accurate (JSON-RPC method names, by-name params).
+- [\`openapi.json\`](./openapi.json): OpenAPI 3.1, the HTTP projection of the same contract (one POST per method).
+
+## Transport
+
+JSON-RPC 2.0 in WebSocket **text** frames on the unix socket \`<root>/daemon.sock\`.
+Params are always a by-name object. **Binary** frames on the same socket carry
+read-only Yjs document sync and are not part of this contract.
+
+The host is chosen by the upgrade path:
+
+| Upgrade | Host |
+| --- | --- |
+| \`/kernel\` | KernelDaemon |
+| \`/project?path=<dir>\` | ProjectDaemon (owns no methods) |
+| \`/session?sessionId=<id>\` | SessionDaemon of an existing session |
+| \`/session?path=<dir>[&sessionId=<id>]\` | SessionDaemon, created if absent |
+
+A method a host does not own falls through session, then project, then kernel.
+A session socket can therefore call kernel methods; a kernel socket answers a
+session method with \`-32601\`.
+
+## Errors
+
+| Code | Meaning |
+| --- | --- |
+| \`-32700\` | Parse error |
+| \`-32600\` | Invalid request |
+| \`-32601\` | Method not found |
+| \`-32602\` | Invalid params (the params failed their schema) |
+| \`-32603\` | Internal error, including a method result that fails its own output schema |
+
+A thrown error with an integer \`code\` keeps that code.
+
+## Parks (UI forms)
+
+A method marked *may park* can answer \`{ "form": "ui", "pending": "<id>", "body": "<scheme>" }\`
+instead of its result; its output is then not validated. The caller answers with
+\`ui/resolve { pending, kind, ... }\` (\`kind\` is \`accept\`, \`cancel\`, \`text\` with \`input\`,
+\`opened\` with \`url\`, or \`dismiss\`). The reply to \`ui/resolve\` is the resumed call's
+result, or another park form. Closing the socket cancels every park it owns.
+In the contract a parking method's output is \`result | UiForm\`.
+
+## Using the contract from an embedder
+
+\`\`\`ts
+import { createHarnessClient, harnessUpgradePath } from "@inhuman.tools/harness-client";
+import { connectUnixSocket } from "@inhuman.tools/harness-client/node";
+
+const transport = await connectUnixSocket({
+  socketPath: "<root>/daemon.sock",
+  target: { host: "session", sessionId },
+});
+const client = createHarnessClient({ transport, onPark: (form) => ui.answer(form) });
+await client.session.kv.set({ key: "model", value: "m", scope: "session" });
+\`\`\`
+
+In a browser or React Native use \`connectWebSocket(url)\` from the main entry
+(\`harnessUpgradePath\` builds the path part). Other transports implement the
+four-member \`Transport\` interface.
+
+Cancelling a call with an \`AbortSignal\` rejects locally; there is no wire
+cancel, so the daemon keeps working on it.
+
+## Regenerating
+
+\`\`\`sh
+pnpm --filter @inhuman.tools/harness-contract spec          # write packages/harness-contract/spec/*
+pnpm --filter @inhuman.tools/harness-contract spec:check    # exit 1 if stale
+\`\`\`
+
+## Client migration note
+
+The web app (\`packages/harness-web-app/src/shell\`), the iOS app and the TUI
+still call through an untyped \`request(method: string, params: unknown)\`.
+They cannot import \`@inhuman.tools/harness\` (it depends on the web app) but they
+can depend on \`harness-contract\` and \`harness-client\`, which depend on neither.
+Migrate one call site at a time: replace \`request("kv/set", {...})\` with
+\`client.session.kv.set({...})\`, or wrap the existing socket in a \`Transport\`.
+
+## Next step: HTTP for SaaS
+
+The contract is already shaped for HTTP (each procedure has a POST route).
+Serving it to remote callers is \`implement(contract)\` plus oRPC's
+\`OpenAPIHandler\` over the same method bodies the daemons run today, behind the
+host's own auth. Not built yet; the JSON-RPC transport remains the only server transport.
+
+## Methods
+
+### Session host
+
+${methodTable(entries, "session")}
+
+### Kernel host
+
+${methodTable(entries, "kernel")}
+
+### Any host
+
+${methodTable(entries, "any")}
+`;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.