feat(packaging): root package.json + committed dist for native bun/npm git+install (#11)

* feat(packaging): add root package.json + commit wrapper dist for git+install

Enables bun/npm consumers to install amplifier-agent-client-ts via native
git URL syntax:

    bun add github:microsoft/amplifier-agent#main

Pattern: a minimal shipping-only package.json at the repo root points
(via 'main', 'types', 'exports') at wrappers/typescript/dist/. The
wrappers/typescript/package.json remains the dev manifest with scripts,
devDependencies, and tsconfig — unchanged.

Trade-off: wrappers/typescript/dist/ is now committed to the repo
(~108KB, 20 files). The CI workflow added in #10 already builds the
wrapper on every push; a follow-up can add an auto-commit step so dist
stays current without manual rebuild discipline. For now, the
'wrapper-v*' tag workflow gives consumers stable pinnable refs.

Why this pattern (vs alternatives):
- npm publish: requires registry account, name commitment, token for
  consumers in some flows. Deferred until POC graduates.
- gitpkg.vercel.app subdir proxy: third-party service, currently
  disabled (HTTP 402 DEPLOYMENT_DISABLED).
- Dist branch (separate refs): requires force-push CI; this is simpler.
- Separate repo for wrapper: needs new repo + code-sync overhead.

Consumer install path (in any project's package.json):

    "amplifier-agent-client-ts": "github:microsoft/amplifier-agent#main"

bun/npm clones the repo, finds package.json at root, the 'files' field
restricts to wrappers/typescript/dist/, the 'exports' field resolves
the entry point. No tokens, no proxies, no registries.

Co-Authored-By: Amplifier <amplifier@microsoft.com>

* fix(packaging): use conditional exports with explicit types resolution

Updates /package.json exports from string form:

  "exports": { ".": "./wrappers/typescript/dist/index.js" }

to conditional form with explicit types resolution:

  "exports": {
    ".": {
      "types": "./wrappers/typescript/dist/index.d.ts",
      "import": "./wrappers/typescript/dist/index.js"
    }
  }

Modern TypeScript (with moduleResolution: bundler/nodenext) follows the
exports field and looks for a 'types' condition before falling back to
the top-level 'types' field. The string-form exports left only 'import'
resolvable, so consumer projects (e.g. NanoClaw's agent-runner) saw
'McpServerConfig' as 'any' or unresolved, surfacing as TS2339 errors
like 'Property transport does not exist on type McpServerConfig'.

Verified locally: NC's bun run typecheck went from 5 errors to 0 after
this change.

Order matters in conditional exports: 'types' MUST appear FIRST so TS
checks it before module conditions. This follows the TypeScript handbook
guidance for the exports field.

Co-Authored-By: Amplifier <amplifier@microsoft.com>

---------

Co-authored-by: Manoj Prabhakar Paidiparthy <mpaidiparthy@microsoft.com>
Co-authored-by: Amplifier <amplifier@microsoft.com>

Author: 3 people

.gitignore

@@ -3,6 +3,7 @@ __pycache__/
 *.py[cod]
 *.egg-info/
 dist/
+!wrappers/typescript/dist/
 build/
 
 # Virtualenvs

package.json

@@ -0,0 +1,25 @@
+{
+  "name": "amplifier-agent-client-ts",
+  "version": "0.3.0",
+  "description": "TypeScript client wrapper for the Amplifier agent Mode A wire (POC: consumed via git+install from github.com/microsoft/amplifier-agent).",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./wrappers/typescript/dist/index.d.ts",
+      "import": "./wrappers/typescript/dist/index.js"
+    }
+  },
+  "types": "./wrappers/typescript/dist/index.d.ts",
+  "files": [
+    "wrappers/typescript/dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/amplifier-agent.git",
+    "directory": "wrappers/typescript"
+  }
+}

wrappers/typescript/.gitignore

@@ -1,4 +1,3 @@
 node_modules/
-dist/
 coverage/
 *.tsbuildinfo

wrappers/typescript/dist/approval.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Approval bridge — in-band, mid-turn JSON-RPC round-trip (§5.2).
+ *
+ * makeApprovalHandler(adapter) returns a JSON-RPC request handler for
+ * 'approval/request' server-initiated requests. Wire it into the
+ * JsonRpcClient via rpc.onRequest('approval/request', makeApprovalHandler(adapter)).
+ *
+ * Decision semantics:
+ *   - 'allow'   — adapter accepted the tool call
+ *   - 'deny'    — adapter rejected, adapter threw, or no adapter configured
+ *   - 'timeout' — adapter did not resolve within timeoutMs
+ *
+ * Pattern reference: Design §5.2 — six-step round-trip.
+ */
+/** Request sent by the engine when a tool call requires approval. */
+export interface ApprovalRequest {
+    id: string;
+    tool: string;
+    args: unknown;
+}
+/** Response the wrapper sends back to the engine. */
+export interface ApprovalResponse {
+    decision: "allow" | "deny" | "timeout";
+    reason?: string;
+    [key: string]: unknown;
+}
+/** Adapter supplied by the host to handle approval requests. */
+export interface ApprovalAdapter {
+    onRequest: (req: unknown) => Promise<ApprovalResponse>;
+    timeoutMs: number;
+}
+/** Handler type matching JsonRpcClient.onRequest signature. */
+export type ApprovalHandler = (params: unknown) => Promise<unknown>;
+/**
+ * Create a JSON-RPC request handler for 'approval/request'.
+ *
+ * @param adapter - Host-supplied adapter, or undefined for default-deny.
+ * @returns An async function (params) => ApprovalResponse.
+ */
+export declare function makeApprovalHandler(adapter: ApprovalAdapter | undefined): ApprovalHandler;

wrappers/typescript/dist/approval.js

@@ -0,0 +1,49 @@
+/**
+ * Approval bridge — in-band, mid-turn JSON-RPC round-trip (§5.2).
+ *
+ * makeApprovalHandler(adapter) returns a JSON-RPC request handler for
+ * 'approval/request' server-initiated requests. Wire it into the
+ * JsonRpcClient via rpc.onRequest('approval/request', makeApprovalHandler(adapter)).
+ *
+ * Decision semantics:
+ *   - 'allow'   — adapter accepted the tool call
+ *   - 'deny'    — adapter rejected, adapter threw, or no adapter configured
+ *   - 'timeout' — adapter did not resolve within timeoutMs
+ *
+ * Pattern reference: Design §5.2 — six-step round-trip.
+ */
+/**
+ * Create a JSON-RPC request handler for 'approval/request'.
+ *
+ * @param adapter - Host-supplied adapter, or undefined for default-deny.
+ * @returns An async function (params) => ApprovalResponse.
+ */
+export function makeApprovalHandler(adapter) {
+    if (!adapter) {
+        return async (_params) => ({
+            decision: "deny",
+            reason: "no_adapter_configured",
+        });
+    }
+    const { onRequest, timeoutMs } = adapter;
+    return async (params) => {
+        let timerId;
+        const timeoutPromise = new Promise((resolve) => {
+            timerId = setTimeout(() => {
+                resolve({ decision: "timeout" });
+            }, timeoutMs);
+        });
+        try {
+            const result = await Promise.race([onRequest(params), timeoutPromise]);
+            // Clear the timeout timer if onRequest won the race.
+            if (timerId !== undefined)
+                clearTimeout(timerId);
+            return result;
+        }
+        catch {
+            if (timerId !== undefined)
+                clearTimeout(timerId);
+            return { decision: "deny", reason: "adapter_error" };
+        }
+    };
+}

wrappers/typescript/dist/argv-builder.d.ts

@@ -0,0 +1,46 @@
+/**
+ * argv-builder.ts — pure argv assembly for `amplifier-agent run`.
+ *
+ * Mode A v2 (task-5 / A3'): given a fully-resolved AssembleArgvInput, produce
+ * the exact argv array the wrapper will pass to the engine binary. This
+ * function performs no I/O and reads no environment — all spilling, env
+ * resolution, and capability composition happen upstream.
+ *
+ * SC-C: the wrapper always passes `-y` to enforce auto-allow at the bundle
+ * layer; approvals are handled by the orchestrating host, not the engine.
+ */
+export interface AssembleArgvInput {
+    /** Session identifier (provided by caller, never generated here). */
+    sessionId: string;
+    /** Final user prompt — emitted last as a positional argument. */
+    prompt: string;
+    /** Protocol version the wrapper speaks (e.g. "0.1.0"). */
+    protocolVersion: string;
+    /** When true, emit `--resume` instead of `--fresh`. */
+    resume?: boolean;
+    /** Working directory override; emits `--cwd <cwd>`. */
+    cwd?: string;
+    /** Provider override; emits `--provider <providerOverride>`. */
+    providerOverride?: string;
+    /**
+     * Pre-resolved value for `--mcp-servers`. Caller decides whether this is
+     * inline JSON or an `@/path/to/file.json` spill reference; argv-builder
+     * threads it through unchanged.
+     */
+    mcpServersFlag?: string;
+    /** Host capabilities object — emitted as `--host-capabilities <JSON>`. */
+    hostCapabilities?: unknown;
+    /** Allowlisted env variable names — emits `--env-allowlist <comma-joined>`. */
+    envAllowlist?: string[];
+    /** Extra env entries — emitted as `--env-extra <JSON>`. */
+    envExtra?: Record<string, string>;
+    /** When true, emit `--allow-protocol-skew`. */
+    allowProtocolSkew?: boolean;
+}
+/**
+ * Build the argv array for `amplifier-agent run`.
+ *
+ * Pure function: no I/O, no env reads, no globals. Order is canonical and
+ * stable so wrapper integration tests can pin against it.
+ */
+export declare function assembleArgv(input: AssembleArgvInput): string[];

wrappers/typescript/dist/argv-builder.js

@@ -0,0 +1,51 @@
+/**
+ * argv-builder.ts — pure argv assembly for `amplifier-agent run`.
+ *
+ * Mode A v2 (task-5 / A3'): given a fully-resolved AssembleArgvInput, produce
+ * the exact argv array the wrapper will pass to the engine binary. This
+ * function performs no I/O and reads no environment — all spilling, env
+ * resolution, and capability composition happen upstream.
+ *
+ * SC-C: the wrapper always passes `-y` to enforce auto-allow at the bundle
+ * layer; approvals are handled by the orchestrating host, not the engine.
+ */
+/**
+ * Build the argv array for `amplifier-agent run`.
+ *
+ * Pure function: no I/O, no env reads, no globals. Order is canonical and
+ * stable so wrapper integration tests can pin against it.
+ */
+export function assembleArgv(input) {
+    const argv = [];
+    argv.push("run");
+    argv.push("--session-id", input.sessionId);
+    argv.push(input.resume ? "--resume" : "--fresh");
+    if (input.cwd !== undefined) {
+        argv.push("--cwd", input.cwd);
+    }
+    if (input.providerOverride !== undefined) {
+        argv.push("--provider", input.providerOverride);
+    }
+    if (input.mcpServersFlag !== undefined) {
+        argv.push("--mcp-servers", input.mcpServersFlag);
+    }
+    if (input.hostCapabilities !== undefined) {
+        argv.push("--host-capabilities", JSON.stringify(input.hostCapabilities));
+    }
+    if (input.envAllowlist !== undefined && input.envAllowlist.length > 0) {
+        argv.push("--env-allowlist", input.envAllowlist.join(","));
+    }
+    if (input.envExtra !== undefined) {
+        argv.push("--env-extra", JSON.stringify(input.envExtra));
+    }
+    argv.push("--output", "json");
+    argv.push("--protocol-version", input.protocolVersion);
+    if (input.allowProtocolSkew === true) {
+        argv.push("--allow-protocol-skew");
+    }
+    // SC-C: wrapper enforces auto-allow at the bundle layer.
+    argv.push("-y");
+    // Prompt is the final positional argument.
+    argv.push(input.prompt);
+    return argv;
+}

wrappers/typescript/dist/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * amplifier-agent-client-ts — public entry point.
+ *
+ * Exports the locked public API from design §8.2, narrowed to Mode A v2
+ * (amendment §5). `spawnAgent` is synchronous-in-spirit: it validates
+ * parameters, resolves the engine binary path, builds the subprocess
+ * environment, and constructs a `SessionHandle`. **No subprocess is spawned
+ * at spawn-time** — the engine is launched per `submit()` (amendment §5.2).
+ */
+export { AaaError, SessionHandle } from "./session.js";
+export type { DisplayEvent, EngineInfo, SessionHandleParams, } from "./session.js";
+export type { ApprovalResponse } from "./approval.js";
+export type { EngineVersionPayload } from "./spawn.js";
+import { SessionHandle } from "./session.js";
+import type { DisplayEvent } from "./session.js";
+import type { ApprovalResponse } from "./approval.js";
+import type { McpServerConfig, HostCapabilities } from "./types.js";
+export type { McpServerConfig, HostCapabilities } from "./types.js";
+/**
+ * The protocol version that this TypeScript wrapper requires.
+ * Forwarded to the engine via `--protocol-version` on every `submit()`.
+ */
+export declare const PROTOCOL_VERSION_REQUIRED_BY_WRAPPER = "0.1.0";
+/** Parameters for spawnAgent(). Signature is locked verbatim by design §8.2. */
+export interface SpawnAgentParams {
+    /** 'burst' reserved; throws AaaError(lifecycle_unsupported) at runtime. */
+    lifecycle: "one-shot";
+    sessionId: string;
+    resume?: boolean;
+    cwd?: string;
+    env?: {
+        allowlist: string[];
+        extra?: Record<string, string>;
+    };
+    providerOverride?: string;
+    /**
+     * Mid-turn approval callback.
+     *
+     * **NOT SUPPORTED IN v1.** Passing a non-null `onRequest` throws
+     * `AaaError(approval_not_supported_in_v1)` at spawnAgent() time. The v1 wire
+     * is Mode A (per-turn subprocess); there is no mid-turn host channel.
+     */
+    approval?: {
+        onRequest: (req: unknown) => Promise<ApprovalResponse>;
+        timeoutMs: number;
+    };
+    display?: {
+        onEvent?: (event: DisplayEvent) => void;
+        subagentEvents?: "all" | "none";
+    };
+    /** Default false; opt out of D6 strict-refuse version check. */
+    allowProtocolSkew?: boolean;
+    /** Optional MCP servers to forward via `--mcp-servers` (A1). */
+    mcpServers?: Record<string, McpServerConfig>;
+    /** Optional host envelope forwarded via `--host-capabilities` (A1). */
+    host?: {
+        capabilities?: HostCapabilities;
+    };
+    /** Per-submit timeout in ms (default: 10 minutes). */
+    timeoutMs?: number;
+    /** Replaces the real resolveBinaryPath() call. */
+    _binaryResolver?: () => string;
+}
+/**
+ * Compose all internal components into the single public entry point.
+ *
+ * Mode A v2 flow (amendment §5):
+ *  1. Guard: lifecycle must be 'one-shot' (D10).
+ *  2. Reject `approval.onRequest !== undefined` (SC-C — v1 has no mid-turn channel).
+ *  3. Resolve engine binary path (or inject via `_binaryResolver`).
+ *  4. Build subprocess environment via `buildEnv`.
+ *  5. Return `new SessionHandle(params)` — **NO subprocess is spawned here**.
+ *
+ * The engine is launched per `submit()` (amendment §5.2). `agent/initialize`
+ * is gone; protocol-version handshake moves to argv at submit-time. Engine
+ * metadata (`engineVersion`, `bundleDigest`) is populated lazily once the
+ * first envelope arrives (TODO: Task-9 wires this from `parseRunOutput`).
+ */
+export declare function spawnAgent(params: SpawnAgentParams): Promise<SessionHandle>;