@mahekara28/context-relay 0.0.0-stage → 0.3.0-beta.1

package/dist/util.d.ts

@@ -0,0 +1,16 @@
+import { type Artifact } from "./model.js";
+export declare const id: () => `${string}-${string}-${string}-${string}-${string}`;
+export declare const now: () => string;
+export declare function canonical(value: unknown): string;
+export declare function digest(value: unknown): string;
+export declare function dataDirectory(explicit?: string): string;
+export declare function privateDirectory(path: string): void;
+export declare function realDirectory(path: string): string;
+export declare function projectFile(root: string, file: string): string;
+export declare function artifact(root: string, file: string): Artifact;
+export declare function gitState(root: string): {
+    head: string | null;
+    branch: string | null;
+};
+/** Best-effort redaction before persistence. Does not guarantee removal of every secret. */
+export declare function redact(text: string): string;

package/dist/util.js

@@ -0,0 +1,86 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { execFileSync } from "node:child_process";
+import { RelayError } from "./model.js";
+export const id = () => randomUUID();
+export const now = () => new Date().toISOString();
+export function canonical(value) {
+    if (Array.isArray(value))
+        return "[" + value.map(canonical).join(",") + "]";
+    if (value !== null && typeof value === "object")
+        return ("{" +
+            Object.entries(value)
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                .map(([k, v]) => JSON.stringify(k) + ":" + canonical(v))
+                .join(",") +
+            "}");
+    return JSON.stringify(value);
+}
+export function digest(value) {
+    return ("sha256:" + createHash("sha256").update(canonical(value)).digest("hex"));
+}
+export function dataDirectory(explicit) {
+    return resolve(explicit ??
+        process.env.CONTEXT_RELAY_HOME ??
+        join(homedir(), ".context-relay"));
+}
+export function privateDirectory(path) {
+    if (existsSync(path) &&
+        (lstatSync(path).isSymbolicLink() || !statSync(path).isDirectory()))
+        throw new RelayError("unsafe_path", "Data directory must be a real directory.");
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+}
+export function realDirectory(path) {
+    const root = realpathSync(resolve(path));
+    if (!statSync(root).isDirectory())
+        throw new RelayError("invalid_project", "Project root must be a directory.");
+    return root;
+}
+export function projectFile(root, file) {
+    if (isAbsolute(file))
+        throw new RelayError("outside_project", "Use a project-relative file path.");
+    const target = realpathSync(resolve(root, file));
+    const rel = relative(root, target);
+    if (rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel))
+        throw new RelayError("outside_project", "File escapes the selected project.");
+    return target;
+}
+export function artifact(root, file) {
+    const target = projectFile(root, file);
+    const info = statSync(target);
+    if (!info.isFile() || info.size > 10 * 1024 * 1024)
+        throw new RelayError("invalid_artifact", "Artifacts must be files no larger than 10 MiB.");
+    const content = readFileSync(target);
+    return {
+        path: relative(root, target).split(sep).join("/"),
+        sha256: "sha256:" + createHash("sha256").update(content).digest("hex"),
+        bytes: content.length,
+    };
+}
+export function gitState(root) {
+    const run = (args) => {
+        try {
+            return (execFileSync("git", ["-C", root, ...args], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: 3000,
+            }).trim() || null);
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        head: run(["rev-parse", "--verify", "HEAD"]),
+        branch: run(["branch", "--show-current"]),
+    };
+}
+/** Best-effort redaction before persistence. Does not guarantee removal of every secret. */
+export function redact(text) {
+    return text
+        .replace(/\b(?:ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9_-]{16,})\b/g, "[REDACTED]")
+        .replace(/(\b(?:authorization\s*:\s*bearer|api[_-]?key\s*[:=]|token\s*[:=]|password\s*[:=])\s*)["']?[^\s"',;]+/gi, "$1[REDACTED]");
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../packages/relay/src/util.ts"],"names":[],"mappings":"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"}

package/docs/HARNESS_CONNECTIONS.md

@@ -0,0 +1,53 @@
+# Harness connections — npm release 0.2
+
+Relay has two independent integration paths: **capture** reads native session history; **MCP** lets a destination agent inspect and accept a reviewed handoff. Installing an MCP server does not expose a harness's chat history.
+
+| Harness | Capture path | MCP setup | Continuation |
+| --- | --- | --- | --- |
+| Claude Code | Project-filtered JSONL under `~/.claude/projects` | Project `.mcp.json` | Open a new chat and ask it to inspect the offered handoff |
+| Codex | Read-only app-server JSON-RPC; paginated completed turns | Project `.codex/config.toml` | Open a trusted project and a new chat; request the handoff |
+| OpenCode | Loopback session/messages HTTP API | Project `opencode.json` | Start a new session and request the handoff |
+| Goose | `session list` and `session export --format json` | `.relay/goose-mcp.json` command manifest | Start Goose with the displayed stdio extension command |
+
+These adapters have synthetic protocol/format tests. They are not a certification of every installed harness version. Native APIs and transcript formats can change; unsupported responses produce visible errors. Relay never edits native chat databases. Completed visible messages and tool results are captured; reasoning blocks and unfinished assistant turns are excluded.
+
+## Connect and capture
+
+```sh
+relay project add --root /absolute/path/to/project
+relay connect --project PROJECT_ID --harness claude
+relay connections --project PROJECT_ID
+relay discover --id CONNECTION_ID
+relay sync --id CONNECTION_ID
+```
+
+Use `--capture-only` to leave MCP settings untouched. Use `--source /path/to/claude/projects` for an alternative transcript root, `--executable /path/to/codex` or `--executable /path/to/goose` for another binary, or `--source http://127.0.0.1:4096` for OpenCode. OpenCode must already be serving; if authentication is enabled, set `OPENCODE_SERVER_PASSWORD` (and optionally `OPENCODE_SERVER_USERNAME`) in the Relay service environment before starting it. Secrets are not stored in connection records.
+
+Capture runs as a background job. The CLI waits for its final result and returns a nonzero exit code on a failed job or any session error. The API exposes progress, errors and cooperative cancellation at session boundaries. Restarted jobs are marked interrupted; recapture is idempotent. Histories are capped at 200 sessions per job, 16 MiB per source response and 20,000 normalized events per import. Changed events with previously captured IDs are rejected atomically rather than silently rewriting history.
+
+Capturing is explicit: Relay does not scan your home directory until you connect and request discovery or capture. Project root matching prevents unrelated sessions from being imported. Review source material before exporting it; built-in credential redaction is best effort, not a secret scanner.
+
+## Disconnect
+
+```sh
+relay disconnect --id CONNECTION_ID
+```
+
+Relay removes only its recorded MCP entry. Other settings remain. If that entry was edited externally, disconnect refuses to overwrite it. Captured history and checkpoints remain available. Reconnecting with `--capture-only` removes the previously managed MCP entry. Goose's manifest is a command reference, not an automatic change to its global extension registry.
+
+## Sources and compatibility contract
+
+- [Claude Code hooks and transcript paths](https://code.claude.com/docs/en/hooks)
+- [Codex app-server protocol](https://learn.chatgpt.com/docs/app-server): `initialize`, `thread/list`, `thread/read`, `thread/turns/list` with `itemsView: full`.
+- [OpenCode SDK and session API](https://opencode.ai/docs/sdk/): session metadata and completed message parts.
+- [Goose CLI commands](https://github.com/aaif-goose/goose/blob/main/documentation/docs/guides/goose-cli-commands.md): JSON list/export support is required.
+
+Relay does not claim to restore hidden model state, automatically merge Git changes, or move files between machines. A handoff carries reviewed instructions, references, file digests and pending work. The receiving agent still verifies its environment and performs the work.
+
+## Interactive continuation in release 0.3
+
+`relay launch --id HANDOFF_ID` opens a fresh Claude Code or Codex interactive session in the registered project with the continuation prompt as one argument. The handoff must be offered and current, and the destination must have a managed MCP connection. It does not use approval-bypass flags or accept the handoff itself. Native model calls may begin in that harness when the user invokes launch; these launches have not been used as live task evaluations in this release. Windows requires a native `.exe` path. OpenCode and Goose retain the explicit prompt/export workflow. See [Claude CLI](https://code.claude.com/docs/en/cli-reference) and [Codex CLI reference](https://developers.openai.com/codex/cli/reference).
+
+Goose native JSON exports serialize `Session.conversation` as a message array; Relay honors `metadata.userVisible` and preserves tool-response roles. The parser also accepts older normalized `messages` exports. The export's working directory is rechecked before import. Source contract: [Goose session export implementation](https://github.com/aaif-goose/goose/blob/main/crates/goose-cli/src/commands/session.rs) and [message types](https://github.com/aaif-goose/goose/blob/main/crates/goose-provider-types/src/conversation/message.rs).
+
+OpenCode projects using `opencode.jsonc` must use capture-only and configure MCP manually; Relay refuses to create a competing JSON config that might shadow existing settings.

package/docs/NPM_QUICKSTART.md

@@ -0,0 +1,150 @@
+# Node CLI and local context service
+
+The npm runtime is available as the public `@mahekara28/context-relay` beta. It requires
+**Node 22.16 or newer** and npm, with no Python prerequisite. Node may print an
+experimental SQLite warning on older supported releases. The existing Python
+API continues to use its own database and release version.
+
+## Install from npm
+
+```sh
+npm install --global @mahekara28/context-relay@beta
+relay --help
+relay ui
+```
+
+Use `@0.3.0-beta.1` instead of `@beta` to install this exact version. Beta updates
+are explicit: rerun the installation command when you want to update.
+
+### Try with npx
+
+```sh
+npx @mahekara28/context-relay@beta demo
+npx @mahekara28/context-relay@beta ui
+```
+
+`npx` downloads the published package into npm's cache and runs its `relay`
+executable. It requires no global installation or Git checkout. Use the full
+scoped name; the unscoped `context-relay` package is a different project.
+Global and npx invocations use the same default local data directory. Add
+`--data-dir /path/to/workspace` to keep a separate profile.
+
+To stop the service and remove a global installation:
+
+```sh
+relay stop
+npm uninstall --global @mahekara28/context-relay
+```
+
+Uninstalling the CLI does not delete your saved local workspace.
+
+### Build from source (contributors)
+
+```sh
+git clone https://github.com/mahekara28/context-relay.git
+cd context-relay
+npm ci --ignore-scripts
+npm run build
+npm pack
+npm install --global ./mahekara28-context-relay-0.3.0-beta.1.tgz
+```
+
+Alternatively use `node dist/cli.js` from the checkout wherever this guide uses
+`relay`. See the [publication procedure](releases/NPM_PUBLISHING.md) for maintainers.
+
+## Try the local workflow
+
+```sh
+relay init
+relay demo
+relay sessions
+```
+
+`demo` creates clearly labeled synthetic webhook conversations in the Relay data
+directory. It prints a checkpoint ID and an offered handoff ID. Substitute those
+IDs below:
+
+```sh
+relay checkpoint packet --id CHECKPOINT_ID
+relay handoff show --id HANDOFF_ID
+relay handoff accept --id HANDOFF_ID --recipient codex
+relay status
+relay stop
+```
+
+Acceptance checks the named recipient, packet digest, captured source revisions,
+selected artifact contents and Git HEAD. It does not prove the coding task is
+complete. New captured events require a fresh checkpoint and offer.
+
+## Register your own project
+
+```sh
+relay project add --root /absolute/path/to/project
+relay project list
+relay import --file session.json
+relay checkpoint create --file checkpoint.json
+```
+
+A normalized session contains `projectId`, `harness` (`claude`, `codex`, `opencode`,
+`goose` or `manual`), `externalId`, `title`, and `events`. Each event has a stable
+`id`, `role`, and `text`; optional fields are `kind` and `timestamp`. Re-importing
+identical events is safe. Reusing an event ID for changed content fails the whole
+batch. Event text receives best-effort credential redaction before persistence.
+
+A checkpoint contains `projectId`, `title`, `goal`, `sources` (session ID and
+expected revision), and optionally `instructions`, `criteria`, `openWork`,
+`evidence`, `files`, `parents`, and `resolutions`. Each instruction has a `key`,
+`text`, and source event references. Inspect the exported Zod schemas in
+[`model.ts`](../packages/relay/src/model.ts) for the complete contract. Files are
+project-relative; references do not transfer their bytes.
+
+The packet budget is **UTF-8 bytes**, not model tokens. Required instructions,
+goal, criteria and open work must fit. Optional evidence can be omitted with a
+count. The contract is `relay.packet/v1`, independently versioned from the
+Python task packet.
+
+## MCP
+
+Register the project first, then configure your MCP client to run:
+
+```sh
+relay mcp --project PROJECT_ID --harness codex
+```
+
+The stdio bridge talks to the same local service as the CLI. It is scoped to that
+project and binds handoff acceptance to the configured harness label. Tools:
+`relay_sessions`, `relay_session_events`, `relay_checkpoints`, `relay_packet`,
+`relay_handoff_inspect`, and `relay_handoff_accept`. A checkpoint resource and
+`continue_task` prompt are also available. MCP does not capture transcripts or
+inject context automatically. Source text remains untrusted evidence.
+
+## Storage and lifecycle
+
+State is local plaintext SQLite in `~/.context-relay`. Use `--data-dir PATH` or
+`CONTEXT_RELAY_HOME` for an isolated profile. Newly created directories and token
+files have private modes where supported by the OS. Keep the profile private;
+local harness labels are not remote-user authentication.
+
+The service binds only to `127.0.0.1` on an available port. API requests require a
+local bearer token and reject foreign Host/Origin headers. The CLI reads its
+private connection descriptor. `relay ui` prints a local browser URL containing
+the access token in its fragment; treat that URL as a credential. Do not expose
+the service through a public proxy. `relay serve` runs in the foreground;
+`relay init` starts a background process. `relay doctor` can recover a lock only
+when its recorded process no longer exists. It never kills another process.
+
+## Release gates
+
+```sh
+npm test
+npm run test:package
+```
+
+The transport suite uses an actual MCP SDK stdio client. The package gate installs
+the tarball into a temporary directory and checks startup, checkpoint creation,
+acceptance, shutdown, persisted state and restart. CI covers Linux, macOS and
+Windows. Live model evaluation remains separate from these offline checks.
+
+## Browser workspace and connections
+
+Run `relay ui` for the bundled local UI, or `relay ui --no-open` to print its local access URL. Follow the [workspace guide](WORKSPACE.md) for source review, merge decisions, handoff export and optional Nebius drafts. The [connection guide](HARNESS_CONNECTIONS.md) documents native history capture separately from MCP access. Use `relay launch --id HANDOFF_ID` for a configured Claude Code/Codex interactive continuation; use `relay handoff export --id HANDOFF_ID` for Markdown.

package/docs/WORKSPACE.md

@@ -0,0 +1,61 @@
+# Local workspace operations
+
+## Start, inspect, stop
+
+`relay ui` starts this profile's service if needed and opens its loopback browser URL. `relay ui --no-open` prints the same URL for manual opening. Treat that URL as a local access credential. The fragment is removed as soon as the page loads; API requests use an Authorization header.
+
+`relay status` reports the service instance. `relay doctor` diagnoses the profile and can recover a lock whose process no longer exists. `relay stop` closes connections, drains capture jobs at source boundaries and closes SQLite. No other process is killed. Concurrent capture for the same connection is rejected. Service logs live under the data directory and do not include request bodies or provider keys.
+
+Use a dedicated `--data-dir` or `CONTEXT_RELAY_HOME` for separate experiments. Keep the same profile option when launching CLI commands from the UI. Back up the entire data directory **after stopping the service**; SQLite may have WAL/SHM sidecars while running. A newer schema is rejected by an older binary. There is no downgrade migration.
+
+## Review and continuation
+
+1. Add an existing project directory and connect a harness.
+2. Discover matching native sessions and choose which to capture.
+3. Select event evidence in **Threads**, then open **Review handoff**.
+4. Fill the goal and current instructions; each instruction needs a cited event. List acceptance criteria, open work and optional project-relative file paths.
+5. Confirm your review, select the recipient and save. The checkpoint is immutable. A failed offer can leave the saved checkpoint available for a new review.
+6. In **Handoffs**, copy the continuation prompt or export Markdown. For configured Claude Code/Codex, `relay launch --id HANDOFF_ID` starts a fresh interactive terminal session in the project. It preserves native approvals and does not accept the handoff automatically. On Windows, launch requires a native `.exe` configured with `--executable`; otherwise use the copied prompt.
+7. The receiving agent inspects and accepts through MCP. Acceptance is not a successful test result.
+
+Review drafts stay in browser memory, with a navigation-away warning. A page reload discards an unsaved draft. Replacing a draft or changing projects asks before discarding it. Browser state is not an authoritative checkpoint. The UI requires a new explicit review after editing fields or applying a model proposal.
+
+**Freshness has a precise scope:** captured source revisions, selected file digests and Git HEAD. It cannot detect native messages that have not yet been captured. Capture again before a consequential handoff. A revision change blocks acceptance; review a new checkpoint rather than editing the old one. Captured character growth is not a model context-window measurement.
+
+## Merge behavior
+
+Select two or more checkpoints, then **Merge selected**. Relay combines references, criteria, open work and file paths. The first goal is a starting point for review. Conflicting instruction keys require a selected resolution; revise the resulting text and sources as needed. The new checkpoint records parents and resolutions. Original checkpoints, native histories and Git files are preserved.
+
+A new review uses latest **captured** source revisions and checks current files when saved. Users must inspect differences; this is not an automatic semantic merge or Git merge.
+
+## Nebius proposals
+
+The provider is optional and keyless operation is the default. Supply a Token Factory key and a model ID available to your account through the service environment:
+
+```sh
+# Set NEBIUS_API_KEY securely in your shell/secret manager first.
+export NEBIUS_MODEL='YOUR_AVAILABLE_MODEL_ID'
+relay stop   # if this profile is already running
+relay ui
+```
+
+On PowerShell use `$env:NEBIUS_MODEL = 'YOUR_AVAILABLE_MODEL_ID'`. Relay does not save the API key in SQLite, configuration JSON, browser state or logs. A service already running must restart to inherit new environment variables.
+
+**Preview → explicit consent → request → schema/citation validation → review.** Only the selected, redacted source events are sent to `https://api.tokenfactory.nebius.com/v1/chat/completions`. Their exact payload is displayed before consent. No filenames, full history or unrelated sessions are added automatically. Model output is returned as a proposal, never as a checkpoint or acceptance.
+
+Limits: 40 events, 48,000 UTF-8 input bytes, 3,000 requested output tokens, 30-second timeout, 128,000 response bytes, no automatic retries. A model must support OpenAI-compatible chat completions with JSON-object output. Truncation, malformed JSON, schema errors, duplicate instruction keys and citations outside the selection are rejected. Costs and availability depend on the selected model; Relay does not estimate them. Provider error bodies are not exposed. Sources: [Nebius Token Factory](https://dev.nebius.com/token-factory).
+
+## Troubleshooting
+
+| Symptom | Next step |
+| --- | --- |
+| No sessions found | Check project root, explicit source, harness installation/API availability and the connection guide. |
+| Changed source ID | The native history changed after capture. Export it under a distinct source identity; Relay refuses to rewrite old evidence silently. |
+| Capture interrupted | Restart capture; already imported events are idempotent. Review partial errors. |
+| Config conflict | Inspect the existing managed MCP entry. Relay refuses to overwrite external edits. |
+| Authentication expired after a restart/port change | Run `relay ui` to open the current service URL. |
+| Handoff is stale | Recapture, inspect changed source/files, and save a newly reviewed checkpoint. |
+| Nebius not configured | Set both environment variables before starting the service; manual review remains available. |
+| Browser cannot copy | Relay shows the prompt in a selectable text area. |
+
+The local workspace is intended for one OS user. API tokens and 0700/0600 permissions protect local state where supported, but the database is not encrypted. The package has no cloud sync, multi-user tenancy, scheduled capture or automatic native thread rewriting.

package/docs/releases/NPM_PUBLISHING.md

@@ -0,0 +1,60 @@
+# Publishing the npm beta
+
+Package: **`@mahekara28/context-relay`**. Registry: **https://registry.npmjs.org/**.
+Publisher: npm user **`mahekara28`**, independently authenticated from GitHub.
+The unscoped `context-relay` package belongs to another project.
+
+## Release procedure
+
+1. Use an isolated npm profile for this account. In the maintainer's dedicated
+   workspace, use its `mahek-npm` launcher for login, identity checks and publishing.
+   Never borrow another account's npm credentials or commit `.npmrc` tokens.
+2. Confirm `npm whoami` returns `mahekara28` in that profile. Complete npm's web
+   login / two-factor challenge if requested. A GitHub PAT is not npm access.
+3. Keep `package.json`, the lockfile, runtime version and docs aligned. Check that
+   the version has not already been published. Published versions cannot be replaced.
+4. Run `npm run typecheck`, `npm test`, `npm run test:package`,
+   `npm run test:browser` and `npm run test:site`. Review the final PR's CI on Linux,
+   macOS and Windows. The package gate uses anonymous, temporary npm config, cache
+   and global prefix, exercises the installed command and npm exec/npx, then
+   verifies the service, UI, demo, handoff and persistence.
+5. Pack once, inspect the file list and preserve that exact tarball:
+
+   ```sh
+   npm pack --json --pack-destination /path/to/release-artifacts
+   npm publish /path/to/release-artifacts/mahekara28-context-relay-0.3.0-beta.1.tgz --dry-run --access public --tag beta
+   ```
+
+6. Publish the inspected tarball using the isolated authenticated npm launcher:
+
+   ```sh
+   npm publish /path/to/release-artifacts/mahekara28-context-relay-0.3.0-beta.1.tgz --access public --tag beta
+   ```
+
+   `publishConfig` defaults to the public npm registry, public access and the
+   `beta` tag. Keep prereleases on `beta`; promoting a stable version to `latest`
+   is a separate release decision. Never put credentials or OTPs in Git history.
+
+7. Read registry metadata and compare `dist.integrity` with the inspected tarball.
+   In an anonymous temporary environment, verify global installation plus
+   `npx @mahekara28/context-relay@beta --version`, `--help`, and a demo/UI lifecycle.
+   Only then merge/deploy documentation that advertises registry installation.
+
+For subsequent automated releases, npm supports [trusted publishing from GitHub
+Actions](https://docs.npmjs.com/trusted-publishers/). Configure that trust explicitly
+on npm before enabling a publishing workflow; the current npm CI builds and tests
+artifacts and does not publish automatically.
+
+## Consumer commands
+
+```sh
+npm install --global @mahekara28/context-relay@beta
+relay ui
+```
+
+```sh
+npx @mahekara28/context-relay@beta ui
+```
+
+Replace `@beta` with `@0.3.0-beta.1` to pin this release. Node 22.16+ is required;
+Git, Python, a frontend build and a model API key are not installation prerequisites.

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@mahekara28/context-relay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0-beta.1",
+  "description": "Review and carry working context between coding agent sessions.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mahek Ara",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "keywords": [
+    "ai-agents",
+    "context",
+    "mcp",
+    "cli",
+    "claude-code",
+    "codex",
+    "opencode",
+    "goose"
+  ],
+  "bugs": {
+    "url": "https://github.com/mahekara28/context-relay/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mahekara28/context-relay.git"
+  },
+  "bin": {
+    "relay": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "dist/*.js.map",
+    "dist/adapters/*.js",
+    "dist/adapters/*.d.ts",
+    "dist/adapters/*.js.map",
+    "dist/ui",
+    "LICENSE",
+    "docs/NPM_QUICKSTART.md",
+    "docs/HARNESS_CONNECTIONS.md",
+    "docs/WORKSPACE.md",
+    "docs/releases/NPM_PUBLISHING.md"
+  ],
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/npm/build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test packages/relay/test/*.test.mjs",
+    "test:package": "node scripts/npm/package-smoke.mjs",
+    "prepack": "npm run build",
+    "test:browser": "npm run build && playwright test",
+    "demo:render": "npm run build && node scripts/npm/render-demo.mjs",
+    "site:build": "node scripts/site/build.mjs",
+    "site:preview": "node scripts/site/preview.mjs",
+    "site:social": "node scripts/site/render-social.mjs",
+    "test:site": "npm run site:build && playwright test --config playwright.site.config.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.64.1",
+    "@types/node": "24.10.0",
+    "prettier": "3.6.2",
+    "typescript": "5.9.3"
+  },
+  "homepage": "https://mahekara28.github.io/context-relay/"
+}