@1kbirds/chidori 3.3.0 → 3.4.1

package/README.md

@@ -3,27 +3,26 @@
 Zero-dependency TypeScript client for a running `chidori serve` instance.
 Uses the global `fetch` (Node 18+, browsers). Mirrors the Python SDK.
 
+> **This package is not the runtime.** It's an optional HTTP client for driving
+> the Chidori **runtime** — the `chidori` binary — from a TypeScript app. You
+> don't need it to write or run agents (those are plain `.ts` files the runtime
+> executes directly). Install the runtime separately, no Rust toolchain needed:
+> `curl -fsSL https://raw.githubusercontent.com/ThousandBirdsInc/chidori/main/scripts/install.sh | sh`
+> — see the [project README](https://github.com/ThousandBirdsInc/chidori#%EF%B8%8F-quick-start).
+
 ## Install
 
 The package is published to npm as
-[`@1kbirds/chidori`](https://www.npmjs.com/package/@1kbirds/chidori) (the
-unscoped `chidori` npm name belongs to an unrelated project). Installing it
-under the `chidori` alias keeps the historical import spelling working:
+[`@1kbirds/chidori`](https://www.npmjs.com/package/@1kbirds/chidori). The
+unscoped `chidori` npm name belongs to an unrelated project, so **always import
+the scoped name** — never `npm install chidori`:
 
 ```bash
-npm install chidori@npm:@1kbirds/chidori
+npm install @1kbirds/chidori
 ```
 
 ```ts
-import { AgentClient, Checkpoint } from "chidori";
-```
-
-Or install under the scoped name directly — the Chidori runtime accepts both
-`"chidori"` and `"@1kbirds/chidori"` as the SDK module specifier in agent
-files:
-
-```bash
-npm install @1kbirds/chidori
+import { AgentClient, Checkpoint } from "@1kbirds/chidori";
 ```
 
 To build from source instead:
@@ -34,16 +33,28 @@ npm install
 npm run build
 ```
 
-Agent and tool authoring types are also exported:
+### Authoring agents and tools
+
+Agent and tool files run *inside* the Chidori runtime, not as a normal Node
+program. They get their authoring types — and the `chidori`/`run` globals — from
+the **virtual** module `chidori:agent`:
 
 ```ts
-import type { Chidori, ToolDefinition } from "chidori";
+/// <reference types="@1kbirds/chidori/agent-env" />
+import type { Chidori, ToolDefinition } from "chidori:agent";
 ```
 
+There is no installable package behind `chidori:agent`; it is a URL-style scheme
+(like `node:fs`) that the runtime strips and injects at execution time, so the
+unrelated `chidori` npm package can never be pulled in by mistake. The
+`/// <reference …>` line (or a `compilerOptions.types: ["@1kbirds/chidori/agent-env"]`
+entry in `tsconfig.json`) gives editors and `tsc` the types while you author;
+the runtime itself needs nothing installed.
+
 ## Usage
 
 ```ts
-import { AgentClient, Checkpoint, isSignalQueued } from "chidori";
+import { AgentClient, Checkpoint, isSignalQueued } from "@1kbirds/chidori";
 
 const client = new AgentClient("http://localhost:8080");
 
@@ -115,3 +126,17 @@ journal/scaffold metadata rather than serialized VM bytes.
 
 Use `client.getSnapshotManifest(sessionId)` when a UI needs only snapshot
 metadata. The endpoint never returns the binary VM snapshot.
+
+## Tests
+
+The SDK ships a dependency-free test suite (Node's built-in `node:test`
+runner) that drives `AgentClient` against a stdlib `node:http` mock server,
+covering run/replay/resume/signal, SSE stream parsing, checkpoint
+serialization, and error handling:
+
+```bash
+npm test   # builds, then runs node --test test/*.test.mjs
+```
+
+End-to-end coverage against a real `chidori serve` binary lives in the Python
+SDK integration tests (`sdk/python/tests/`).

package/dist/agent-env.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Ambient types for the virtual `chidori:agent` module.
+ *
+ * Agent and tool files written for the Chidori runtime import their authoring
+ * types — and, in the global style, the `chidori`/`run` values — from
+ * `chidori:agent`:
+ *
+ * ```ts
+ * import type { Chidori, ToolDefinition } from "chidori:agent";
+ * // …or the global style:
+ * import { chidori, run } from "chidori:agent";
+ * ```
+ *
+ * There is no installable package behind that specifier. It is a virtual module
+ * the runtime injects, much like `node:fs` or `bun:test`: the runtime strips the
+ * import and supplies the real values when it executes the file, so nothing is
+ * resolved from npm. Crucially, the unrelated `chidori` package on npm can never
+ * be pulled in by mistake, because `chidori:agent` is not a registry name at all.
+ *
+ * This file exists only so editors and `tsc` can type agent files. Pull it into
+ * a project with a triple-slash reference at the top of an agent or tool file:
+ *
+ * ```ts
+ * /// <reference types="@1kbirds/chidori/agent-env" />
+ * import type { Chidori } from "chidori:agent";
+ * ```
+ *
+ * or once, project-wide, via tsconfig `compilerOptions.types`:
+ * `["@1kbirds/chidori/agent-env"]`.
+ *
+ * NOTE: this must stay a script file (no top-level `import`/`export`). A bare
+ * `declare module "chidori:agent"` is a *global* ambient declaration; adding a
+ * top-level `export` would turn it into a module augmentation and fail to
+ * resolve, since there is no real `chidori:agent` module to augment.
+ */
+declare module "chidori:agent" {
+    export * from "@1kbirds/chidori/agent";
+}

package/dist/agent-env.js

@@ -0,0 +1 @@
+"use strict";

package/dist/agent.d.ts

@@ -463,7 +463,7 @@ export type ToolFunction<TArgs extends JsonObject = JsonObject, TResult extends
  * need for a `(input, chidori)` second parameter):
  *
  * ```ts
- * import { chidori, run } from "chidori";
+ * import { chidori, run } from "chidori:agent";
  * run(async (input: { topic: string }) => {
  *   await chidori.log("starting", { topic: input.topic });
  *   return { ok: true };
@@ -480,7 +480,7 @@ export declare const chidori: Chidori;
  * named `agent`" convention.
  *
  * ```ts
- * import { run } from "chidori";
+ * import { run } from "chidori:agent";
  * run(async (input) => ({ greeting: `hello ${input.name}` }));
  * ```
  */

package/dist/agent.js

@@ -13,7 +13,7 @@
  * need for a `(input, chidori)` second parameter):
  *
  * ```ts
- * import { chidori, run } from "chidori";
+ * import { chidori, run } from "chidori:agent";
  * run(async (input: { topic: string }) => {
  *   await chidori.log("starting", { topic: input.topic });
  *   return { ok: true };
@@ -35,7 +35,7 @@ export const chidori = new Proxy({}, {
  * named `agent`" convention.
  *
  * ```ts
- * import { run } from "chidori";
+ * import { run } from "chidori:agent";
  * run(async (input) => ({ greeting: `hello ${input.name}` }));
  * ```
  */

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@1kbirds/chidori",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "description": "TypeScript SDK for the Chidori agent framework — HTTP client plus agent authoring types.",
+  "keywords": ["ai", "agents", "typescript", "llm", "replay"],
   "publishConfig": { "access": "public" },
   "homepage": "https://github.com/ThousandBirdsInc/chidori",
   "repository": { "type": "git", "url": "https://github.com/ThousandBirdsInc/chidori.git" },
@@ -17,12 +18,18 @@
     "./agent": {
       "import": "./dist/agent.js",
       "types": "./dist/agent.d.ts"
+    },
+    "./agent-env": {
+      "import": "./dist/agent-env.js",
+      "types": "./dist/agent-env.d.ts"
     }
   },
   "files": ["dist", "src", "README.md"],
   "scripts": {
     "build": "tsc",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "pretest": "tsc",
+    "test": "node --test test/*.test.mjs"
   },
   "devDependencies": {
     "typescript": "^5.4.0"

package/src/agent-env.ts

@@ -0,0 +1,43 @@
+/**
+ * Ambient types for the virtual `chidori:agent` module.
+ *
+ * Agent and tool files written for the Chidori runtime import their authoring
+ * types — and, in the global style, the `chidori`/`run` values — from
+ * `chidori:agent`:
+ *
+ * ```ts
+ * import type { Chidori, ToolDefinition } from "chidori:agent";
+ * // …or the global style:
+ * import { chidori, run } from "chidori:agent";
+ * ```
+ *
+ * There is no installable package behind that specifier. It is a virtual module
+ * the runtime injects, much like `node:fs` or `bun:test`: the runtime strips the
+ * import and supplies the real values when it executes the file, so nothing is
+ * resolved from npm. Crucially, the unrelated `chidori` package on npm can never
+ * be pulled in by mistake, because `chidori:agent` is not a registry name at all.
+ *
+ * This file exists only so editors and `tsc` can type agent files. Pull it into
+ * a project with a triple-slash reference at the top of an agent or tool file:
+ *
+ * ```ts
+ * /// <reference types="@1kbirds/chidori/agent-env" />
+ * import type { Chidori } from "chidori:agent";
+ * ```
+ *
+ * or once, project-wide, via tsconfig `compilerOptions.types`:
+ * `["@1kbirds/chidori/agent-env"]`.
+ *
+ * NOTE: this must stay a script file (no top-level `import`/`export`). A bare
+ * `declare module "chidori:agent"` is a *global* ambient declaration; adding a
+ * top-level `export` would turn it into a module augmentation and fail to
+ * resolve, since there is no real `chidori:agent` module to augment.
+ */
+declare module "chidori:agent" {
+  // Re-export every authoring type plus the `chidori`/`run` value globals from
+  // the SDK's agent module. Ambient module declarations may only reference
+  // other modules by a non-relative (package) name, so we use the package's own
+  // public subpath. The package's build resolves it via the `paths` mapping in
+  // tsconfig.json; consumers resolve it from `node_modules`.
+  export * from "@1kbirds/chidori/agent";
+}

package/src/agent.ts

@@ -508,7 +508,7 @@ export type ToolFunction<TArgs extends JsonObject = JsonObject, TResult extends
  * need for a `(input, chidori)` second parameter):
  *
  * ```ts
- * import { chidori, run } from "chidori";
+ * import { chidori, run } from "chidori:agent";
  * run(async (input: { topic: string }) => {
  *   await chidori.log("starting", { topic: input.topic });
  *   return { ok: true };
@@ -533,7 +533,7 @@ export const chidori: Chidori = new Proxy({} as Chidori, {
  * named `agent`" convention.
  *
  * ```ts
- * import { run } from "chidori";
+ * import { run } from "chidori:agent";
  * run(async (input) => ({ greeting: `hello ${input.name}` }));
  * ```
  */