@crouter/sdk 0.3.377

package/README.md

@@ -0,0 +1,170 @@
+# @crouter/sdk — a typed Node and browser client for running crouter agents from your application
+
+![crouter](https://raw.githubusercontent.com/crouton-labs/crouter/main/assets/banner.svg)
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@crouter/sdk"><img alt="npm" src="https://img.shields.io/npm/v/@crouter/sdk?label=npm"></a>
+  <a href="https://github.com/crouton-labs/crouter/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/license-GPL--3.0-blue"></a>
+</p>
+
+`@crouter/sdk` is the application-facing client for a crouter daemon (`crtrd`). Create an agent run, wait for a result checked against a Zod or Standard Schema, stream the run's text and tool calls to a UI, and use the daemon's other APIs: files, bash, documents ("memory"), crons, human requests, and the OAuth connection flow for apps whose users each have their own runtime. It is ESM-only.
+
+It is a client, not a runtime. It never runs an agent itself, and it does not bundle a model: the daemon it talks to does, using the provider that daemon is signed in to. In Node, `new Crouter()` connects to the local daemon over its unix socket and starts it on the first request if it is not running. In a browser or from another machine it needs the daemon's TCP URL and a bearer token. The lower-level contract it is built on is [`@crouter/api`](../crouter-api); most applications should install this package instead.
+
+[Docs](https://docs.crouter.ai/docs/sdk) · [Client construction](https://docs.crouter.ai/docs/sdk/client) · [Resource map](https://docs.crouter.ai/docs/sdk/resources) · [Recipes](https://docs.crouter.ai/docs/sdk/guides) · [crouter repository](https://github.com/crouton-labs/crouter)
+
+## Install
+
+```bash
+npm install @crouter/sdk zod   # zod is optional; any Standard Schema works for output_schema
+npm install -g crouter         # the daemon and the crtr CLI
+crtr sys setup                 # sign in to a model provider (first run only)
+```
+
+## Connect
+
+In Node, `new Crouter()` uses the local unix socket and starts the daemon on the first request when the socket is cold. In a browser or a remote process, pass the TCP URL and bearer token returned by `crtr sys connect` — the owner token, or a scoped token from `crtr sys connect --scopes` whose list caps what the application and its runs may do. Call `client.auth.status()` before enabling a run button: its `instructions` tells the user what to do when `next_step` is not `null`.
+
+```ts
+import Crouter from '@crouter/sdk';
+
+const client = new Crouter();
+const status = await client.auth.status();
+
+if (status.next_step !== null) {
+  console.log(status.instructions);
+} else {
+  console.log('The daemon and selected provider are ready.');
+}
+```
+
+```ts
+const client = new Crouter({
+  baseURL: 'http://127.0.0.1:8787',
+  token: 'the-token-from-crtr-sys-connect',
+});
+```
+
+## Run and parse a result
+
+`parse()` creates a root run, waits for its outcome, and types `output_parsed` from a Zod or Standard Schema. Pass `scopes` to give a run a per-run allow-list; under a scoped token the list must stay inside the token's ceiling, and omitting it gives the run the ceiling.
+
+```ts
+import Crouter from '@crouter/sdk';
+import { z } from 'zod';
+
+const client = new Crouter();
+const run = await client.nodes.parse({
+  prompt: 'Read package.json and return its name and version.',
+  cwd: '/absolute/path/to/project',
+  scopes: ['crtr:llm', 'crtr:files:read:user:.'],
+  output_schema: z.object({ name: z.string(), version: z.string() }),
+});
+
+if (run.kind === 'result') console.log(run.output_parsed.name, run.output_parsed.version);
+else if (run.reason === 'declined') console.warn(run.declined?.reason);
+else console.error(run.reason, run.detail);
+```
+
+## Stream a run
+
+`nodes.stream()` creates a run and opens its event stream. `followActivity()` turns tool-call events into snapshots for an activity view. Disconnecting or calling `stream.abort()` stops the stream, not the run.
+
+```ts
+import { followActivity } from '@crouter/sdk';
+
+const stream = client.nodes.stream({
+  prompt: 'Inspect the repository and report the failing tests.',
+  cwd: '/absolute/path/to/project',
+});
+
+for await (const steps of followActivity(stream)) {
+  renderActivity(steps);
+}
+
+const outcome = await stream.finalOutcome();
+console.log(outcome.kind);
+```
+
+## Follow the reply to a message
+
+On a run, `runs.reply(runId, sent)` follows the turn that answers one `runs.message` and ends when that turn completes. `turn.completed.error` reports a refused (`content_refused`) or failed (`model_error`) model call.
+
+```ts
+const sent = await client.runs.message(runId, 'Hello');
+const text = await client.runs.reply(runId, sent).text();
+```
+
+To answer a first message in the run's first turn, pass it to `runs.start`: `message` is stored with the run and always joins the first turn as context ahead of `prompt`, and the result's `message` is what `runs.reply` takes. (A `runs.message(id, text, {start_turn: false})` sent after `runs.start` joins the first turn only if it is stored before the run claims that turn's messages.)
+
+```ts
+const run = await client.runs.start({prompt: instructions, message: 'Hello'});
+const {text, ended, error} = await client.runs.reply(run.run_id, run.message!).collect({onDelta: (delta) => send(delta)});
+// ended: 'completed' | 'error' (see error) | 'waiting_on_user' | 'settled' (see outcome)
+```
+
+`collect` (and `text({onDelta})`) passes each streamed piece to `onDelta`, starting a later assistant message with a blank line, and resolves to the trimmed messages joined by a blank line. The raw `RunReplyEvent` iterator stays available.
+
+A run working in the background reports what it is doing on `runs.get(runId).activity` (`starting`, `thinking`, `tool` with `tool.name` and `tool.summary`, `writing`, or `between_turns`; `null` once it is no longer `running`), so a polling page shows progress without reading `runs.trace`.
+
+`runs.listAll(filters)` and `memory.listAll(params)` (the person's knowledge and preference documents the caller can read: `public` by default, every privacy level with `crtr:memory:manage:user`) iterate every item across pages with `for await`, fetching the next page only as you go. `runs.delete(runId)` deletes a running run too — it stops the run's turns and sandboxes itself, so there is no need to `cancel` first; deleting a run that is already gone throws `NotFoundError`.
+
+## Read files and run bash
+
+File paths and the bash working directory are absolute. `bash.run()` returns non-zero exits as values.
+
+```ts
+const source = await client.files.read('/absolute/path/to/project/package.json');
+const command = await client.bash.run({
+  command: 'npm test',
+  cwd: '/absolute/path/to/project',
+  timeout_s: 60,
+});
+
+console.log(source.content, command.exit_code);
+```
+
+## PostgreSQL connection store (Node)
+
+For a multi-process OAuth app, install `pg` in the app (`npm install pg`) and import the optional `@crouter/sdk/stores/postgres` subpath; the SDK's main entry never loads `pg`. `new PostgresConnectionStore(pool, { table: 'connection' })` implements `load`, `save`, `lock`, and `listStale(before: Date)`. Use one shared database and the same table for all workers. The lock keeps one PostgreSQL transaction and client open across the entire refresh callback (including the token request), so provision the pool for concurrent refreshes and avoid a transaction timeout shorter than the request. The table name accepts one or two lowercase SQL identifiers (schema.table), never SQL fragments.
+
+Create the table before using the store (or adapt this schema in your migration):
+
+```sql
+CREATE TABLE connection (
+  user_id text PRIMARY KEY,
+  runtime_url text NOT NULL,
+  refresh_token text NOT NULL,
+  grant_id text NOT NULL,
+  access_token text NOT NULL,
+  access_token_expires_at timestamptz NOT NULL,
+  id_token text,
+  updated_at timestamptz NOT NULL DEFAULT clock_timestamp()
+);
+CREATE INDEX connection_updated_at_idx ON connection (updated_at, user_id);
+```
+
+`save` upserts all fields and sets `updated_at` to the database clock. `listStale(before)` selects connections with `updated_at < before`, oldest first; it is a **last save** timestamp, not necessarily last successful refresh if an app also calls `save` for another reason. For idle-token maintenance, schedule `oauth.refreshIdleConnections(store, {olderThanMs: 30 * 24 * 60 * 60 * 1000})` (for example, daily). It selects stale connections, refreshes under the store lock, reloads there to avoid rotating an already-used token, saves a rotated connection, and reports `{refreshed, failures}` for the worker to inspect; each failure's `reason` is `refreshRefusal(error)`. `refreshRefusal(error)` classifies any refused refresh as `'removed'` (`grant_removed`: the runtime deleted the app's runs; delete what you store for the person), `'paused'` (`grant_suspended`: nothing was deleted; keep the data until they sign in again), `'reconnect'` (`refresh_token_expired`, `refresh_token_reused`, `grant_revoked`: nothing was deleted; ask them to sign in again), or `null` when the error is not the directory refusing a refresh. Load the signing key `crouter-sdk keygen` wrote with `privateKey: await privateKeyFromFile('local/app-key.json')` (Node), or check one from an environment variable with `parsePrivateJwk(text)`; both refuse anything but a private JWK with a `kid`. The SDK does not start a timer. `listStale` returns connections, not timestamps, so a worker needing a strict cutoff recheck must maintain that policy separately. The table contains credentials: restrict database access, encrypt backups, and delete a row when its user disconnects. PostgreSQL `timestamptz` must be returned as a JavaScript `Date` (the `pg` default parser).
+
+## Example application
+
+See the complete [localhost SDK demo](https://github.com/crouton-labs/crouter/tree/main/examples/localhost-demo) for streaming, structured output, and an HTTP plugin in one local page.
+
+## Reference
+
+The [SDK guide](https://docs.crouter.ai/docs/sdk) covers [client construction](https://docs.crouter.ai/docs/sdk/client), [nodes and scopes](https://docs.crouter.ai/docs/sdk/nodes), [streaming](https://docs.crouter.ai/docs/sdk/streaming), [files](https://docs.crouter.ai/docs/sdk/files), [bash](https://docs.crouter.ai/docs/sdk/bash), [Docker](https://docs.crouter.ai/docs/sdk/docker), [errors](https://docs.crouter.ai/docs/sdk/errors), and the complete [resource map](https://docs.crouter.ai/docs/sdk/resources).
+
+`@crouter/sdk/errors` exports `errorCodes`/`ErrorCode` (the daemon's codes), `sdkErrorCodes`/`SdkErrorCode` (the codes the SDK raises itself, such as `oauth_state_mismatch`; `CrouterError.code` is typed with them), and `mapError`, which turns a plain `APIError` into its status class (`NotFoundError`, …) for app tests.
+
+The SDK re-exports its public DTO types, so you do not also install `@crouter/api`.
+
+## Related
+
+- [`@crouter/api`](../crouter-api): the `/v1` contract this client is built on.
+- [`@crouter/env-docker`](../crouter-env-docker): start a `crtrd` container and get a `Connection` to pass to `new Crouter(...)`.
+- [`@crouter/plugin`](../crouter-plugin): expose your own commands to agents as `crtr` commands.
+- [Main repository](https://github.com/crouton-labs/crouter): the `crtr` CLI, the `crtrd` daemon, and [contributing guidelines](https://github.com/crouton-labs/crouter/blob/main/CONTRIBUTING.md).
+
+## License
+
+[GPL-3.0-only](https://github.com/crouton-labs/crouter/blob/main/LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,153 @@
+import { type HealthDTO, type MessageResultDTO, type NodeDetailDTO, type ListNodesQuery, type NodeOutcomeDTO, type NodeOutcomeResponseDTO, type NodeSummaryDTO, type ProfileDTO, type ReportDTO, type ReportsQuery, type StatusDTO } from '@crouter/api';
+import { Bash } from './resources/bash.js';
+import { Canvas } from './resources/canvas.js';
+import { Crons } from './resources/crons.js';
+import { CustomObjects } from './resources/custom-objects.js';
+import { Attachments } from './resources/attachments.js';
+import { Files } from './resources/files.js';
+import { Human } from './resources/human.js';
+import { Models } from './resources/models.js';
+import { NodesResource } from './resources/nodes.js';
+import { NodeStream } from './resources/node-stream.js';
+import { Questions } from './resources/questions.js';
+import { Providers } from './resources/providers.js';
+import { Runs } from './resources/runs.js';
+import { Shares } from './resources/shares.js';
+import { Memory } from './resources/memory.js';
+import { Uploads } from './resources/uploads.js';
+import type { AuthStatus, AuthStatusParams, CancelParams, EnsureProfileParams, MessageParams, NodeCreateParams, NodeEventsOptions, NodeOutcomeOptions, OutputSchema, ParsedOutcome, RequestOptions, SchemaOutput } from './types.js';
+import type { AppProfile } from './resources/runs.js';
+type CoreNodes = {
+    create: (params: NodeCreateParams, options?: RequestOptions) => Promise<NodeDetailDTO>;
+    retrieve: (id: string, options?: RequestOptions) => Promise<NodeDetailDTO>;
+    list: (query?: ListNodesQuery, options?: RequestOptions) => Promise<NodeSummaryDTO[]>;
+    outcome: (id: string, options?: NodeOutcomeOptions) => Promise<NodeOutcomeResponseDTO>;
+    waitForOutcome: (id: string, options?: RequestOptions) => Promise<NodeOutcomeDTO>;
+    createAndWait: (params: NodeCreateParams, options?: RequestOptions) => Promise<NodeOutcomeDTO>;
+    parse: <TSchema extends OutputSchema>(params: NodeCreateParams & {
+        output_schema: TSchema;
+    }, options?: RequestOptions) => Promise<ParsedOutcome<SchemaOutput<TSchema>>>;
+    message: (id: string, body: string | MessageParams, options?: RequestOptions) => Promise<MessageResultDTO>;
+    cancel: (id: string, body?: CancelParams, options?: RequestOptions) => Promise<unknown>;
+    interrupt: (id: string, options?: RequestOptions) => Promise<unknown>;
+    stream: (params: NodeCreateParams, options?: RequestOptions) => NodeStream;
+    events: (id: string, options?: NodeEventsOptions) => NodeStream;
+    reports: {
+        list: (id: string, query?: ReportsQuery, options?: RequestOptions) => Promise<ReportDTO[]>;
+    };
+};
+/** Connection settings for a Crouter daemon. `headers` lets a Docker environment's
+ * `connection()` result pass directly to this constructor. */
+export interface CrouterOptions {
+    /** `http(s)://host:port` of a daemon TCP listener. Defaults to `CRTR_BASE_URL`. */
+    baseURL?: string;
+    /** Unix socket path. Node only. Defaults to `CRTR_SOCKET`, else `$CRTR_HOME/crtrd.sock`, else `~/.crouter/canvas/crtrd.sock`. */
+    socketPath?: string;
+    /** Sent as `Authorization: Bearer <token>`. Defaults to `CRTRD_TOKEN`. A unix-socket daemon ignores it. */
+    token?: string;
+    /** Supplies a directory token per request, including reconnects. Mutually exclusive with token. */
+    tokenSource?: () => Promise<string>;
+    /** Refreshes a connection-backed token once after a 401. */
+    onUnauthorized?: () => Promise<void>;
+    /** Per-request wall clock in milliseconds. Defaults to 30000. Does not apply to a stream. */
+    timeout?: number;
+    /** Transient-failure retries. Defaults to 2. Never applied to `POST` or `PATCH`. */
+    maxRetries?: number;
+    /** Merged into every request. */
+    defaultHeaders?: Record<string, string>;
+    /** Merged after `defaultHeaders`; the `Authorization` generated from `token` still wins. */
+    headers?: Record<string, string>;
+    /** Transport override, for proxies and instrumentation. */
+    fetch?: typeof fetch;
+    /** On a cold socket, run `crtr sys daemon start` and retry once. Node only. Defaults to true for a socket, false for `baseURL`. */
+    autostart?: boolean;
+}
+/**
+ * The client, and the only class an application constructs. Each namespace below wraps a
+ * family of daemon routes; `request` is the escape hatch for a route with no wrapper.
+ */
+export declare class Crouter {
+    /** Create, inspect, message, stream, and wait on nodes. */
+    readonly nodes: NodesResource & CoreNodes;
+    /** Run one command in an absolute working directory. */
+    readonly bash: Bash;
+    /** Canvas-wide views: attention, snapshot, roster, dashboard, prune, and history. */
+    readonly canvas: Canvas;
+    /** Scheduled commands. */
+    readonly crons: Crons;
+    /** Register, publish, receive, and acknowledge custom canvas objects. */
+    readonly customObjects: CustomObjects;
+    /** Human requests and the human inbox. */
+    readonly human: Human;
+    /** Model credentials and model configuration. */
+    readonly models: Models;
+    /** Agent profiles. */
+    readonly profiles: {
+        ensure: (name: string, params?: EnsureProfileParams, options?: RequestOptions) => Promise<ProfileDTO>;
+        retrieve: (name: string, options?: RequestOptions) => Promise<ProfileDTO>;
+        /** The profiles an app may start runs with (app listener only): its own, and those of other apps its grant covers. `default` marks its default profile. */
+        list: (options?: RequestOptions) => Promise<{
+            profiles: AppProfile[];
+        }>;
+    };
+    /** Daemon status and health. */
+    readonly system: {
+        status: (options?: RequestOptions) => Promise<StatusDTO>;
+        health: (options?: RequestOptions) => Promise<HealthDTO>;
+    };
+    /** Whether this client can reach a daemon that can run a model. */
+    readonly auth: {
+        status: (params?: AuthStatusParams, options?: RequestOptions) => Promise<AuthStatus>;
+    };
+    /** Read, write, and list absolute host paths. */
+    readonly files: Files;
+    readonly runs: Runs;
+    /** Uploads to runtime storage, for files a run prompt or message names (app listener only). */
+    readonly uploads: Uploads;
+    /** Signed links to files a run received as attachments (app listener only). */
+    readonly attachments: Attachments;
+    /** Public share links to files (app listener only). */
+    readonly shares: Shares;
+    /** Questions agents in runs ask the user (app listener only). */
+    readonly questions: Questions;
+    /** Read the documents the person owns (`store: 'user'`): an app sees their `public` documents, and every privacy level with a `crtr:memory:manage:user` grant. */
+    readonly memory: Memory;
+    /** Scope-filtered provider tools and daemon-mediated calls. */
+    readonly providers: Providers;
+    readonly grant: {
+        get: (options?: RequestOptions) => Promise<import('@crouter/api').GrantGetDTO>;
+    };
+    readonly health: {
+        get: (options?: RequestOptions) => Promise<{
+            status: 'ok';
+            api_version: string;
+        }>;
+    };
+    private readonly eventFetch;
+    private readonly bearerToken;
+    private connectionToken;
+    private readonly tokenSource;
+    private readonly onUnauthorized;
+    private readonly client;
+    private readonly timeout;
+    private readonly baseURL;
+    private readonly socketPath;
+    constructor(options?: CrouterOptions);
+    /** Establish NDJSON through the JSON client's cold-socket/retry transport; leave the live body unread. */
+    private openCustomDeliveries;
+    private openRunEvents;
+    /** `GET /v1/files/download` as a raw fetch: bytes are not JSON, so it bypasses the JSON client but
+     *  still goes through `call()`, which supplies the connection token and refreshes it once on a 401. */
+    private openDownload;
+    /** Sends one request to any daemon route, for routes the namespaces above do not wrap. */
+    request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    private authStatus;
+    private stream;
+    private events;
+    private outcome;
+    private waitForOutcome;
+    private createAndWait;
+    private parse;
+    private call;
+}
+export {};