@agentic-kit/pi-host 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @agentic-kit/pi-host
+
+The host side of a headless agent run. `@agentic-kit` already owns the loop
+(`@agentic-kit/agent`), the tools (`@agentic-kit/pi`) and the gating policy
+(`@agentic-kit/harness`); what a workload has to supply is the three small
+host-shaped things those packages ask for, and nothing here re-implements any of
+them.
+
+| Existing contract | What this package supplies |
+| --- | --- |
+| `GateHost` (`@agentic-kit/harness`) | `createThreadGateHost` — approval through the conversation thread |
+| `ConfirmGate` (`createConfirmGate`) | `createGatedToolset` — wraps `AgentTool.execute` with the harness gate |
+| `PiToolsHost` (`@agentic-kit/pi/host`) | `createPiToolsHost` — built from values, not from a desktop session |
+| `AgentEvent` (`@agentic-kit/agent`) | `TranscriptWriter` — events → `agent_message` / `agent_task` |
+
+## Approval is a message, so `hasUI` is true
+
+`GateHost.hasUI` does not mean "a window exists": it means a human decision is
+obtainable. A Job can obtain one — it writes the pending call into the thread at
+`approval-requested` and waits for the human to echo it back — so the runner
+reports `true`. Reporting `false` would tell the harness no decision is possible
+and every tool in `MUTATING_DB_TOOLS` would be refused before it ran.
+
+The gate is the harness's. `createGatedToolset` calls `gate.onToolCall(...)` and,
+when the gate blocks, returns the gate's own reason to the model as an ordinary
+tool result — a declined call is information the agent can act on, not a crash.
+pi's fs/edit/bash/git tools are not in `MUTATING_DB_TOOLS` and are never gated:
+the whole point of the coding lane is that editing the clone is free.
+
+## Credentials do not go in the clone
+
+`@agentic-kit/pi` resolves tenant context with `resolveProjectContext(cwd)`,
+which reads `<cwd>/.env` for `ACCESS_TOKEN` and `DATABASE_ID`. In this lane `cwd`
+is a cloned git repository that the agent is about to `git add -A` and push, so
+writing platform credentials there is a credential-exfiltration bug waiting for
+a careless commit. The coding lane therefore runs with the coding tool set and no
+project context in the work tree. A lane that genuinely needs control-plane tools
+calls `materializeProjectContext({ dir, workTree, ... })`, which writes a `0600`
+`.env` **outside** the work tree and throws
+`ProjectContextInsideWorkTreeError` if asked to do otherwise.
+
+## Persona
+
+`loadPersona` / `loadPersonaSkills` / `selectPersona` turn an `agent_persona` row
+and the `agent_resource` rows it names into the model, system prompt, temperature
+and tool subset for the run. A persona that asks for a tool the lane does not
+carry throws (`UnknownPersonaToolError`) rather than running with a quietly
+smaller toolbox, and a named resource that is missing or inactive throws rather
+than dropping a skill the operator expected to be in force.
+
+## Tests
+
+`pnpm test` — the gate against a fake thread (approve / decline / cancel /
+timeout), the writer against a fake agent run, persona selection, the gated
+toolset, and the project-context guard.
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/events.d.ts

@@ -0,0 +1,47 @@
+import type { AgentEvent } from '@agentic-kit/agent';
+import type { TaskWriter, TodoItem, Transcript } from '@agentic-kit/agent-conversation';
+/** Tool names whose arguments carry the agent's todo list. */
+export declare const TODO_TOOL_NAMES: string[];
+export interface TranscriptWriterOptions {
+    transcript: Transcript;
+    /** Absent when the tenant's agent module has no task surface for this run. */
+    tasks?: TaskWriter;
+    /** Tool names whose arguments carry a todo list. */
+    todoToolNames?: string[];
+}
+/**
+ * Translate a run's events into thread writes.
+ *
+ * Nothing here is best-effort: a failed write is kept and rethrown from
+ * `drain()`, because a transcript that silently lost the middle of a run is
+ * worse than a run that fails.
+ */
+export declare class TranscriptWriter {
+    private readonly options;
+    private chain;
+    private readonly pending;
+    private readonly todoToolNames;
+    private failure;
+    constructor(options: TranscriptWriterOptions);
+    /** Subscribe this writer to an agent: `agent.subscribe(writer.handler)`. */
+    readonly handler: (event: AgentEvent) => void;
+    /** Wait for every write queued so far, and surface the first that failed. */
+    drain(): Promise<void>;
+    private enqueue;
+    private apply;
+    private syncTodos;
+}
+/** The prose of an assistant message; thinking and tool calls are not prose. */
+export declare function assistantText(message: {
+    content: unknown;
+}): string;
+/** The text of a tool result, as the transcript records it. */
+export declare function resultText(result: {
+    content: unknown;
+}): string;
+/**
+ * The todo list a todo tool was called with. Returns null when the arguments do
+ * not carry one; throws when they carry a malformed one, because a todo list the
+ * tasks table cannot represent is a bug rather than an absence.
+ */
+export declare function parseTodos(args: Record<string, unknown>): TodoItem[] | null;

package/esm/events.js

@@ -0,0 +1,161 @@
+// `AgentEvent` → the thread.
+//
+// `@agentic-kit/agent` already emits everything a transcript needs, so this is a
+// translation and nothing else: prose to a message, a tool call to a ToolPart
+// rewritten in place as it runs, the agent's todo list to `agent_task` rows.
+// Writes are serialized through one promise chain so the thread's order matches
+// the run's order; `drain()` is how a composition root waits for the tail.
+import { completeToolPart, failToolPart, toolPart } from '@agentic-kit/agent-conversation';
+import { asOneOf, asRecord, asString } from '@constructive-io/coerce';
+/** The text of a content block, or '' when the block carries none. */
+const blockText = (block) => asString(asRecord(block)?.text) ?? '';
+/** Tool names whose arguments carry the agent's todo list. */
+export const TODO_TOOL_NAMES = ['todo_write', 'update_plan', 'write_todos'];
+/**
+ * Translate a run's events into thread writes.
+ *
+ * Nothing here is best-effort: a failed write is kept and rethrown from
+ * `drain()`, because a transcript that silently lost the middle of a run is
+ * worse than a run that fails.
+ */
+export class TranscriptWriter {
+    options;
+    chain = Promise.resolve();
+    pending = new Map();
+    todoToolNames;
+    failure;
+    constructor(options) {
+        this.options = options;
+        this.todoToolNames = new Set(options.todoToolNames ?? TODO_TOOL_NAMES);
+    }
+    /** Subscribe this writer to an agent: `agent.subscribe(writer.handler)`. */
+    handler = (event) => {
+        this.enqueue(() => this.apply(event));
+    };
+    /** Wait for every write queued so far, and surface the first that failed. */
+    async drain() {
+        await this.chain;
+        if (this.failure !== undefined) {
+            const failure = this.failure;
+            this.failure = undefined;
+            throw failure;
+        }
+    }
+    enqueue(work) {
+        this.chain = this.chain.then(async () => {
+            if (this.failure !== undefined)
+                return;
+            try {
+                await work();
+            }
+            catch (error) {
+                this.failure = error;
+            }
+        });
+    }
+    async apply(event) {
+        switch (event.type) {
+            case 'message_end': {
+                if (event.message.role !== 'assistant')
+                    return;
+                const text = assistantText(event.message);
+                if (text)
+                    await this.options.transcript.appendText(text);
+                return;
+            }
+            case 'tool_execution_start': {
+                const part = toolPart({
+                    toolName: event.toolName,
+                    toolCallId: event.toolCallId,
+                    input: event.args
+                });
+                const message = await this.options.transcript.appendToolPart(part);
+                this.pending.set(event.toolCallId, { messageId: message.id, part });
+                await this.syncTodos(event.toolName, event.args);
+                return;
+            }
+            case 'tool_execution_end': {
+                const call = this.pending.get(event.toolCallId);
+                if (!call) {
+                    throw new Error(`tool call ${event.toolCallId} (${event.toolName}) ended without having started`);
+                }
+                this.pending.delete(event.toolCallId);
+                const output = resultText(event.result);
+                const next = event.isError
+                    ? failToolPart(call.part, output || 'The tool failed without a message')
+                    : completeToolPart(call.part, output);
+                await this.options.transcript.updateToolPart(call.messageId, next);
+                return;
+            }
+            case 'tool_decision_pending': {
+                // The lane's tools declare no `decision` schema — approval is the
+                // harness gate, answered through the thread. An in-band decision would
+                // stall the run forever, so it fails loudly instead.
+                throw new Error(`tool ${event.toolName} (${event.toolCallId}) asked for an in-band decision, which this runner does not serve`);
+            }
+            default:
+                return;
+        }
+    }
+    async syncTodos(toolName, args) {
+        if (!this.options.tasks || !this.todoToolNames.has(toolName))
+            return;
+        const todos = parseTodos(args);
+        if (todos)
+            await this.options.tasks.sync(todos);
+    }
+}
+/** The prose of an assistant message; thinking and tool calls are not prose. */
+export function assistantText(message) {
+    const content = message.content;
+    const prose = asString(content);
+    if (prose)
+        return prose.trim();
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .map((block) => (asRecord(block)?.type === 'text' ? blockText(block) : ''))
+        .join('')
+        .trim();
+}
+/** The text of a tool result, as the transcript records it. */
+export function resultText(result) {
+    const content = result.content;
+    const text = asString(content);
+    if (text)
+        return text;
+    if (!Array.isArray(content))
+        return '';
+    return content.map(blockText).join('').trim();
+}
+const TODO_STATUSES = ['pending', 'in_progress', 'completed', 'failed'];
+/**
+ * The todo list a todo tool was called with. Returns null when the arguments do
+ * not carry one; throws when they carry a malformed one, because a todo list the
+ * tasks table cannot represent is a bug rather than an absence.
+ */
+export function parseTodos(args) {
+    const raw = args.todos ?? args.items ?? args.plan;
+    if (raw === undefined || raw === null)
+        return null;
+    if (!Array.isArray(raw))
+        throw new Error('todo tool called with a non-list todo argument');
+    return raw.map((entry, index) => {
+        const item = asRecord(entry);
+        if (!item)
+            throw new Error(`todo ${index} is not an object`);
+        const description = asString(item.description ?? item.content ?? item.title ?? item.step);
+        if (!description)
+            throw new Error(`todo ${index} carries no description`);
+        const status = asOneOf(item.status ?? 'pending', TODO_STATUSES);
+        if (!status) {
+            throw new Error(`todo ${index} has status "${String(item.status)}", which agent_task does not model`);
+        }
+        const error = asString(item.error);
+        return {
+            description: description.trim(),
+            status,
+            ...(error ? { error } : {})
+        };
+    });
+}

package/esm/gate.d.ts

@@ -0,0 +1,35 @@
+import type { Inbox, ToolPart, Transcript } from '@agentic-kit/agent-conversation';
+import type { GateHost } from '@agentic-kit/harness';
+export interface ThreadGateHostOptions {
+    transcript: Transcript;
+    inbox: Inbox;
+    /** How long a pending approval waits before it is treated as declined. */
+    approvalTimeoutMs?: number;
+    /** Approval ids, as a value — a suite passes a counter. */
+    newApprovalId?: () => string;
+    /** Called when the human asked the run to stop while an approval was pending. */
+    onCancel?: (reason: string | undefined) => void;
+    /** Called with every tool part the gate writes, so a caller can trace the run. */
+    onToolPart?: (part: ToolPart) => void;
+}
+export declare const DEFAULT_APPROVAL_TIMEOUT_MS: number;
+/**
+ * The harness's `GateHost` plus the drain its one synchronous method needs.
+ *
+ * `notifyToolSkipped` returns void, so its transcript write cannot be awaited
+ * where it is called. It is queued instead, and `drain()` — awaited by the
+ * composition root once the run ends — rethrows the first failure, so a write
+ * that fails still fails the Job rather than disappearing into a `catch`.
+ */
+export type ThreadGateHost = GateHost & {
+    drain(): Promise<void>;
+};
+/**
+ * A `GateHost` whose UI is the thread.
+ *
+ * The pending call is one message whose single ToolPart is rewritten in place as
+ * the decision arrives, so the thread reads as a conversation and the state
+ * machine in `@agentic-kit/agent-conversation` is the only place the
+ * lifecycle is enforced.
+ */
+export declare function createThreadGateHost(options: ThreadGateHostOptions): ThreadGateHost;

package/esm/gate.js

@@ -0,0 +1,88 @@
+// The GateHost the harness already defines, answered by the conversation.
+//
+// `@agentic-kit/harness` owns *what* is gated (`MUTATING_DB_TOOLS`), the prompt
+// wording (`buildConfirmPrompt`) and the decline guard; a host only supplies the
+// three capabilities in `GateHost`. Desktop answers `confirmTool` with a dialog.
+// A Job answers it with a message: it writes the tool call into the thread at
+// `approval-requested` and waits for the human to echo the part back at
+// `approval-responded`. That is the same contract, resolved asynchronously —
+// which is exactly why the runner reports `hasUI: true`. Reporting false would
+// tell the gate no decision can ever be obtained and block every mutating tool.
+import { denyToolPart, failToolPart, isApprovalEvent, requestApproval, respondToApproval, toolPart } from '@agentic-kit/agent-conversation';
+export const DEFAULT_APPROVAL_TIMEOUT_MS = 15 * 60 * 1000;
+/**
+ * A `GateHost` whose UI is the thread.
+ *
+ * The pending call is one message whose single ToolPart is rewritten in place as
+ * the decision arrives, so the thread reads as a conversation and the state
+ * machine in `@agentic-kit/agent-conversation` is the only place the
+ * lifecycle is enforced.
+ */
+export function createThreadGateHost(options) {
+    const { transcript, inbox, approvalTimeoutMs = DEFAULT_APPROVAL_TIMEOUT_MS, newApprovalId = () => `approval-${Math.random().toString(36).slice(2, 10)}`, onCancel, onToolPart } = options;
+    const emit = (part) => {
+        onToolPart?.(part);
+        return part;
+    };
+    const confirmTool = async (toolCallId, title, message, preview) => {
+        const pending = toolPart({
+            toolName: 'confirm',
+            toolCallId,
+            input: { title, message, ...(preview ? { preview } : {}) }
+        });
+        const requested = emit(requestApproval(pending, newApprovalId()));
+        const written = await transcript.appendToolPart(requested);
+        const outcome = await inbox.waitFor(isApprovalEvent, { timeoutMs: approvalTimeoutMs });
+        if (outcome.event && outcome.event.toolCallId === toolCallId) {
+            // Two writes on a decline, on purpose: `approval-responded` is the human's
+            // answer and `output-denied` is the call's outcome, and the transcript is
+            // read as a history — collapsing them would lose who declined and why.
+            const responded = respondToApproval(requested, {
+                approved: outcome.event.approved,
+                reason: outcome.event.reason
+            });
+            await transcript.updateToolPart(written.id, emit(responded));
+            if (!outcome.event.approved) {
+                await transcript.updateToolPart(written.id, emit(denyToolPart(responded, outcome.event.reason ?? 'Declined by the user')));
+            }
+            return outcome.event.approved;
+        }
+        if (outcome.event) {
+            // A decision arrived for a call this gate is not waiting on. The gate is
+            // serial — one pending confirm at a time — so this is a malformed client,
+            // not a race, and silently dropping it would strand the run.
+            throw new Error(`approval for tool call ${outcome.event.toolCallId} arrived while ${toolCallId} was pending`);
+        }
+        if (outcome.cancelled) {
+            onCancel?.(outcome.cancelled.reason);
+            await transcript.updateToolPart(written.id, emit(denyToolPart(requested, outcome.cancelled.reason ?? 'Cancelled by the user')));
+            return false;
+        }
+        await transcript.updateToolPart(written.id, emit(failToolPart(requested, `No decision within ${Math.round(approvalTimeoutMs / 1000)}s`)));
+        return false;
+    };
+    // Queued notices, serialized so the transcript keeps the order the gate saw,
+    // and their first failure, kept for `drain()` to rethrow.
+    let queue = Promise.resolve();
+    let failure;
+    return {
+        hasUI: true,
+        confirmTool,
+        notifyToolSkipped: (toolCallId) => {
+            queue = queue.then(async () => {
+                try {
+                    await transcript.appendText(`Skipped a repeat of a declined tool call (${toolCallId}).`);
+                }
+                catch (error) {
+                    failure ??= error;
+                }
+            });
+        },
+        drain: async () => {
+            await queue;
+            if (failure !== undefined) {
+                throw new Error(`failed to write a skipped-tool notice to the thread: ${failure instanceof Error ? failure.message : String(failure)}`, { cause: failure });
+            }
+        }
+    };
+}

package/esm/host.d.ts

@@ -0,0 +1,18 @@
+import type { ToolsHost } from '@agentic-kit/pi/host';
+export interface PiHostValues {
+    userId: string;
+    accessToken: string;
+    apiKey?: string;
+    apiEndpoint?: string;
+    modulesEndpoint?: string;
+}
+/**
+ * A `ToolsHost` built from values.
+ *
+ * The desktop host reads an Electron singleton; a Job has a token and two
+ * endpoints, and nothing else. It offers no preview token, no data-auth broker
+ * and no step-up, so the data-plane tools decline cleanly rather than half-work,
+ * and no `deliverSecret`, so `create_api_key` refuses to mint a secret that has
+ * nowhere safe to go.
+ */
+export declare function createPiToolsHost(values: PiHostValues): ToolsHost;

package/esm/host.js

@@ -0,0 +1,26 @@
+// The `ToolsHost` a Job can honestly provide.
+/**
+ * A `ToolsHost` built from values.
+ *
+ * The desktop host reads an Electron singleton; a Job has a token and two
+ * endpoints, and nothing else. It offers no preview token, no data-auth broker
+ * and no step-up, so the data-plane tools decline cleanly rather than half-work,
+ * and no `deliverSecret`, so `create_api_key` refuses to mint a secret that has
+ * nowhere safe to go.
+ */
+export function createPiToolsHost(values) {
+    if (!values.accessToken)
+        throw new Error('a pi tools host needs an access token');
+    return {
+        account: () => ({
+            userId: values.userId,
+            accessToken: values.accessToken,
+            ...(values.apiKey ? { apiKey: values.apiKey } : {})
+        }),
+        backendConfig: () => ({
+            ...(values.apiEndpoint ? { apiEndpoint: values.apiEndpoint } : {}),
+            ...(values.modulesEndpoint ? { modulesEndpoint: values.modulesEndpoint } : {})
+        }),
+        signInHint: 'This run was launched without a usable platform token.'
+    };
+}

package/esm/index.d.ts

@@ -0,0 +1,16 @@
+export type { TranscriptWriterOptions } from './events';
+export { assistantText, parseTodos, resultText, TODO_TOOL_NAMES, TranscriptWriter } from './events';
+export type { ThreadGateHost, ThreadGateHostOptions } from './gate';
+export { createThreadGateHost, DEFAULT_APPROVAL_TIMEOUT_MS } from './gate';
+export type { PiHostValues } from './host';
+export { createPiToolsHost } from './host';
+export type { MeteredIdentity, MeteredModel, MeteredModelOptions } from './model';
+export { createMeteredModel, gatewayApiRoot, meteringHeaders } from './model';
+export type { LoadPersonaInput, PersonaConfig, PersonaRow, PersonaSelection, SelectPersonaInput, SkillResource } from './persona';
+export { loadPersona, loadPersonaSkills, PersonaModelUnresolvedError, PersonaNotFoundError, selectPersona, UnknownPersonaToolError } from './persona';
+export type { ProjectContextRequest } from './project-context';
+export { isInside, materializeProjectContext, ProjectContextInsideWorkTreeError } from './project-context';
+export type { GatedToolset, GatedToolsetOptions } from './tools';
+export { CLONE_GATE_DEPS, createGatedToolset } from './tools';
+export type { WorkspaceToolsOptions } from './workspace-tools';
+export { createWorkspaceTools, DEFAULT_COMMAND_TIMEOUT_MS, MAX_READ_BYTES, OutsideWorkspaceError, WORKSPACE_TOOL_NAMES } from './workspace-tools';

package/esm/index.js

@@ -0,0 +1,12 @@
+// @agentic-kit/pi-host — the host half of a headless agent run: the
+// harness's `GateHost` answered by the conversation thread, persona selection,
+// the gated toolset, and `AgentEvent` → transcript. Every dependency arrives as
+// a value; nothing here knows what a `ctx` is.
+export { assistantText, parseTodos, resultText, TODO_TOOL_NAMES, TranscriptWriter } from './events';
+export { createThreadGateHost, DEFAULT_APPROVAL_TIMEOUT_MS } from './gate';
+export { createPiToolsHost } from './host';
+export { createMeteredModel, gatewayApiRoot, meteringHeaders } from './model';
+export { loadPersona, loadPersonaSkills, PersonaModelUnresolvedError, PersonaNotFoundError, selectPersona, UnknownPersonaToolError } from './persona';
+export { isInside, materializeProjectContext, ProjectContextInsideWorkTreeError } from './project-context';
+export { CLONE_GATE_DEPS, createGatedToolset } from './tools';
+export { createWorkspaceTools, DEFAULT_COMMAND_TIMEOUT_MS, MAX_READ_BYTES, OutsideWorkspaceError, WORKSPACE_TOOL_NAMES } from './workspace-tools';

package/esm/model.d.ts

@@ -0,0 +1,39 @@
+import type { AssistantMessageEventStream, Context, ModelDescriptor, StreamOptions } from '@agentic-kit/chat';
+/** Who the inference is billed to. Mirrors the http runtime's `AgentHeaders`. */
+export interface MeteredIdentity {
+    databaseId: string;
+    entityId?: string | null;
+    organizationId?: string | null;
+    actorId?: string | null;
+}
+export interface MeteredModelOptions extends MeteredIdentity {
+    /** `AGENTIC_SERVER_URL` — the gateway's root, with or without `/v1`. */
+    agenticServerUrl: string;
+    /** The model id the persona selected. */
+    model: string;
+    /** Injectable for tests; defaults to the runtime's `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export interface MeteredModel {
+    model: ModelDescriptor;
+    /** `Agent`'s `streamFn`. */
+    streamFn: (model: ModelDescriptor, context: Context, options?: StreamOptions) => AssistantMessageEventStream;
+}
+/**
+ * The identity headers `agentic-server` meters against. `X-Database-Id` is
+ * required; the billing entity falls back the way the node runtime falls back,
+ * so a run launched without an entity still bills the actor's personal org.
+ */
+export declare function meteringHeaders(identity: MeteredIdentity): Record<string, string>;
+/**
+ * The gateway's OpenAI-compatible api root, `<host>/v1`, whichever form the
+ * projection took.
+ *
+ * `AGENTIC_SERVER_URL` is documented as the bare root, but an operator reading a
+ * provider's own docs sets it with `/v1` — and `resolveMeteredGateway` accepts
+ * both, so the two halves of one stack disagreed: appending `/v1` unconditionally
+ * posted to `<host>/v1/v1/chat/completions`, which the gateway answers with a 404
+ * that surfaces as "no assistant message" naming no url.
+ */
+export declare function gatewayApiRoot(agenticServerUrl: string): string;
+export declare function createMeteredModel(options: MeteredModelOptions): MeteredModel;