@agentic-kit/pi-host 0.2.0

package/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;

package/model.js

@@ -0,0 +1,216 @@
+"use strict";
+// The model a resource Job talks to: the tenant's metered gateway, never a
+// provider.
+//
+// `agentic-server` is OpenAI-compatible and already deployed as the platform's
+// `AGENTIC_SERVER_URL`, and the three identity headers it meters on are the
+// ones `compute/runtimes/node/src/agent.ts` already sends. So the model
+// descriptor is the agentic stack's own (`OpenAIAdapter.createModel`), pointed
+// at that base URL, and nothing here holds a provider key: the gateway owns the
+// credential, the quota and the ledger.
+//
+// The transport is the one thing that cannot be the adapter's. `OpenAIAdapter`
+// only speaks SSE (`stream: true`), and the gateway is a request/response proxy
+// — it reads the upstream answer with `response.json()` and meters the `usage`
+// block, which a streamed answer does not carry. So `streamFn` below is a
+// single non-streaming POST rendered as the event stream `Agent` consumes: one
+// `text_start`/`text_delta`/`text_end` for the answer, one `toolcall_end` per
+// tool call, then `done`. Every event the agent loop and the transcript writer
+// need, and no second metering path.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.meteringHeaders = meteringHeaders;
+exports.gatewayApiRoot = gatewayApiRoot;
+exports.createMeteredModel = createMeteredModel;
+const chat_1 = require("@agentic-kit/chat");
+/**
+ * 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.
+ */
+function meteringHeaders(identity) {
+    const headers = { 'X-Database-Id': identity.databaseId };
+    const billingEntity = identity.entityId ?? identity.organizationId ?? identity.actorId;
+    if (billingEntity)
+        headers['X-Entity-Id'] = billingEntity;
+    if (identity.actorId)
+        headers['X-Actor-Id'] = identity.actorId;
+    return headers;
+}
+/**
+ * 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.
+ */
+function gatewayApiRoot(agenticServerUrl) {
+    return `${agenticServerUrl.replace(/\/+$/, '').replace(/\/v1$/, '')}/v1`;
+}
+function createMeteredModel(options) {
+    const { agenticServerUrl, model } = options;
+    if (!agenticServerUrl) {
+        throw new Error('a coding run needs AGENTIC_SERVER_URL — inference goes through the metered ' +
+            'gateway, and a resource Job that cannot reach it has no provider of its own');
+    }
+    const headers = { 'Content-Type': 'application/json', ...meteringHeaders(options) };
+    const apiRoot = gatewayApiRoot(agenticServerUrl);
+    const url = `${apiRoot}/chat/completions`;
+    const doFetch = options.fetchImpl ?? fetch;
+    const adapter = new chat_1.OpenAIAdapter({
+        baseUrl: apiRoot,
+        provider: 'agentic-server',
+        headers
+    });
+    const streamFn = (descriptor, context, streamOptions) => {
+        const stream = (0, chat_1.createAssistantMessageEventStream)();
+        void (async () => {
+            const message = (0, chat_1.createAssistantMessage)(descriptor);
+            try {
+                stream.push({ type: 'start', partial: message });
+                const response = await doFetch(url, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(buildRequestBody(descriptor, context, streamOptions)),
+                    ...(streamOptions?.signal ? { signal: streamOptions.signal } : {})
+                });
+                if (!response.ok) {
+                    const body = await response.text().catch(() => '');
+                    throw new Error(`agentic server answered ${response.status}: ${body}`);
+                }
+                const completion = (await response.json());
+                const reason = finish(completion, applyCompletion(message, descriptor, completion, stream));
+                message.stopReason = reason;
+                stream.push({ type: 'done', reason, message });
+                stream.end(message);
+            }
+            catch (error) {
+                message.stopReason = streamOptions?.signal?.aborted ? 'aborted' : 'error';
+                message.errorMessage = error instanceof Error ? error.message : String(error);
+                stream.push({
+                    type: 'error',
+                    reason: message.stopReason === 'aborted' ? 'aborted' : 'error',
+                    error: message
+                });
+                stream.end(message);
+            }
+        })();
+        return stream;
+    };
+    return { model: adapter.createModel(model), streamFn };
+}
+/** Fill the message from the completion and emit the events that describe it. */
+function applyCompletion(message, descriptor, completion, stream) {
+    const choice = completion.choices?.[0];
+    const text = choice?.message?.content ?? '';
+    if (text) {
+        const contentIndex = message.content.length;
+        message.content.push({ type: 'text', text });
+        stream.push({ type: 'text_start', contentIndex, partial: message });
+        stream.push({ type: 'text_delta', contentIndex, delta: text, partial: message });
+        stream.push({ type: 'text_end', contentIndex, content: text, partial: message });
+    }
+    let calls = 0;
+    for (const raw of choice?.message?.tool_calls ?? []) {
+        const toolCall = toToolCall(raw, calls);
+        const contentIndex = message.content.length;
+        message.content.push(toolCall);
+        stream.push({ type: 'toolcall_start', contentIndex, partial: message });
+        if (toolCall.rawArguments) {
+            stream.push({ type: 'toolcall_delta', contentIndex, delta: toolCall.rawArguments, partial: message });
+        }
+        stream.push({ type: 'toolcall_end', contentIndex, toolCall, partial: message });
+        calls += 1;
+    }
+    const usage = completion.usage ?? {};
+    message.usage.input = usage.prompt_tokens ?? 0;
+    message.usage.output = usage.completion_tokens ?? 0;
+    message.usage.totalTokens =
+        usage.total_tokens ?? (usage.prompt_tokens ?? 0) + (usage.completion_tokens ?? 0);
+    (0, chat_1.calculateUsageCost)(descriptor, message.usage);
+    return calls > 0;
+}
+function toToolCall(raw, index) {
+    const toolCall = (0, chat_1.createToolCall)(raw.id ?? `call_${index}`, raw.function?.name ?? '');
+    const rawArguments = raw.function?.arguments ?? '';
+    if (rawArguments) {
+        toolCall.rawArguments = rawArguments;
+        // A model that answers with unparseable arguments is the model's error to
+        // recover from, so the call still reaches the agent — with no arguments,
+        // which the tool will reject — rather than ending the run here.
+        try {
+            toolCall.arguments = JSON.parse(rawArguments);
+        }
+        catch {
+            toolCall.arguments = {};
+        }
+    }
+    return toolCall;
+}
+function finish(completion, hasToolCalls) {
+    if (hasToolCalls)
+        return 'toolUse';
+    return completion.choices?.[0]?.finish_reason === 'length' ? 'length' : 'stop';
+}
+function buildRequestBody(model, context, options) {
+    const body = {
+        model: model.id,
+        messages: [
+            ...(context.systemPrompt ? [{ role: 'system', content: context.systemPrompt }] : []),
+            ...context.messages.map(toOpenAIMessage)
+        ]
+    };
+    if (options?.maxTokens !== undefined)
+        body.max_tokens = options.maxTokens;
+    if (options?.temperature !== undefined)
+        body.temperature = options.temperature;
+    if (context.tools && context.tools.length > 0) {
+        body.tools = context.tools.map((tool) => ({
+            type: 'function',
+            function: { name: tool.name, description: tool.description, parameters: tool.parameters }
+        }));
+    }
+    return body;
+}
+function toOpenAIMessage(message) {
+    if (message.role === 'user') {
+        return {
+            role: 'user',
+            content: typeof message.content === 'string'
+                ? message.content
+                : message.content
+                    .map((block) => (block.type === 'text' ? block.text : `[image:${block.mimeType}]`))
+                    .join('\n')
+        };
+    }
+    if (message.role === 'toolResult') {
+        return {
+            role: 'tool',
+            tool_call_id: message.toolCallId,
+            content: message.content
+                .map((block) => (block.type === 'text' ? block.text : `[image:${block.mimeType}]`))
+                .join('\n')
+        };
+    }
+    const text = message.content
+        .filter((block) => block.type === 'text' || block.type === 'thinking')
+        .map((block) => (block.type === 'text' ? block.text : `<thinking>${block.thinking}</thinking>`))
+        .join('\n');
+    const toolCalls = message.content
+        .filter((block) => block.type === 'toolCall')
+        .map((block) => ({
+        id: block.id,
+        type: 'function',
+        function: {
+            name: block.name,
+            arguments: block.rawArguments ?? JSON.stringify(block.arguments)
+        }
+    }));
+    return {
+        role: 'assistant',
+        content: text.length > 0 ? text : null,
+        ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {})
+    };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@agentic-kit/pi-host",
+  "version": "0.2.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "The host side of a headless agent run: a GateHost that asks for approval through the conversation thread, persona → model/prompt/tools selection, and an AgentEvent → transcript/task writer.",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "agentic-kit",
+    "pi",
+    "coding-agent",
+    "run-log",
+    "constructive"
+  ],
+  "dependencies": {
+    "@agentic-kit/agent-conversation": "^0.2.0",
+    "@constructive-io/coerce": "^0.4.1"
+  },
+  "peerDependencies": {
+    "@agentic-kit/agent": "^0.19.0",
+    "@agentic-kit/chat": "^1.18.0",
+    "@agentic-kit/harness": "^0.15.0",
+    "@agentic-kit/pi": "^0.22.2"
+  },
+  "gitHead": "9bba983b38395277e0400294aaa380e586b049d4"
+}

package/persona.d.ts

@@ -0,0 +1,85 @@
+import type { GraphQLClient } from '@agentic-kit/agent-conversation';
+export interface PersonaRow {
+    id: string;
+    slug: string;
+    name: string;
+    systemPrompt: string | null;
+    resources: (string | null)[] | null;
+    config: PersonaConfig | null;
+}
+/** `agent_persona.config`, as this runner reads it. Unknown keys are ignored. */
+export interface PersonaConfig {
+    model?: string;
+    temperature?: number;
+    /** Tool names the persona is allowed to use. Absent means "every tool the lane offers". */
+    tools?: string[];
+    /** Tool names withheld from the persona, applied after `tools`. */
+    excludeTools?: string[];
+    maxSteps?: number;
+}
+export interface SkillResource {
+    slug: string;
+    title: string;
+    kind: string | null;
+    body: string;
+}
+export declare class PersonaNotFoundError extends Error {
+    readonly ref: string;
+    constructor(ref: string);
+}
+export declare class UnknownPersonaToolError extends Error {
+    readonly persona: string;
+    readonly missing: string[];
+    readonly available: string[];
+    constructor(persona: string, missing: string[], available: string[]);
+}
+export declare class PersonaModelUnresolvedError extends Error {
+    readonly persona: string;
+    constructor(persona: string);
+}
+export interface LoadPersonaInput {
+    client: GraphQLClient;
+    databaseId: string;
+    /** One of the two; the id wins when both are given. */
+    personaId?: string | null;
+    personaSlug?: string | null;
+}
+/** The persona row, or null when the run was given neither an id nor a slug. */
+export declare function loadPersona(input: LoadPersonaInput): Promise<PersonaRow | null>;
+/** The `agent_resource` rows a persona names, in the order it named them. */
+export declare function loadPersonaSkills(input: {
+    client: GraphQLClient;
+    databaseId: string;
+    persona: PersonaRow;
+}): Promise<SkillResource[]>;
+export interface PersonaSelection {
+    personaId: string | null;
+    model: string;
+    systemPrompt: string;
+    temperature?: number;
+    maxSteps?: number;
+    /** Tool names, filtered by the persona's `tools`/`excludeTools`. */
+    toolNames: string[];
+    skills: SkillResource[];
+}
+export interface SelectPersonaInput {
+    persona: PersonaRow | null;
+    skills?: SkillResource[];
+    /** Every tool the lane offers, by name. */
+    availableToolNames: string[];
+    /**
+     * The deployment's own configured default, used when the persona names no
+     * model. Absent is legal and means "someone must choose": a run billed
+     * against a model nobody picked is worse than a run that refuses to start, so
+     * a selection with neither raises `PersonaModelUnresolvedError`.
+     */
+    defaultModel?: string | undefined;
+    /** Used when the persona carries no system prompt. */
+    defaultSystemPrompt: string;
+}
+/**
+ * Resolve what the run should be configured with. Skill bodies are appended to
+ * the prompt — the harness's skill overlay materializes files for hosts that
+ * have a filesystem contract with the model; here the prompt is the contract.
+ */
+export declare function selectPersona(input: SelectPersonaInput): PersonaSelection;

package/persona.js

@@ -0,0 +1,131 @@
+"use strict";
+// Persona → model, prompt, tools, skills.
+//
+// The agent module already models all four: `agent_persona.system_prompt` is the
+// prompt, `agent_persona.config` is the model/tool preferences, and
+// `agent_persona.resources` names `agent_resource` rows (kind `skill` /
+// `knowledge` / `convention`) by slug. The run reads them; it invents none of
+// them, and a persona that names a tool the lane does not carry is an error
+// rather than a silent narrowing — an operator who wrote `apply_migration` into
+// a persona should hear that the coding lane does not offer it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersonaModelUnresolvedError = exports.UnknownPersonaToolError = exports.PersonaNotFoundError = void 0;
+exports.loadPersona = loadPersona;
+exports.loadPersonaSkills = loadPersonaSkills;
+exports.selectPersona = selectPersona;
+const PERSONA_FIELDS = 'id slug name systemPrompt resources config';
+const PERSONA_BY_SLUG = `query CodeTaskPersonaBySlug($databaseId: UUID!, $slug: String!) {
+  agentPersonas(
+    where: { databaseId: { equalTo: $databaseId }, slug: { equalTo: $slug } }
+    first: 1
+  ) { nodes { ${PERSONA_FIELDS} } }
+}`;
+const PERSONA_BY_ID = `query CodeTaskPersonaById($id: UUID!) {
+  agentPersona(id: $id) { ${PERSONA_FIELDS} }
+}`;
+const RESOURCES_BY_SLUG = `query CodeTaskPersonaResources($databaseId: UUID!, $slugs: [String!]) {
+  agentResources(
+    where: { databaseId: { equalTo: $databaseId }, slug: { in: $slugs }, isActive: { equalTo: true } }
+  ) { nodes { slug title kind body } }
+}`;
+class PersonaNotFoundError extends Error {
+    ref;
+    constructor(ref) {
+        super(`no active agent persona for ${ref}`);
+        this.ref = ref;
+        this.name = 'PersonaNotFoundError';
+    }
+}
+exports.PersonaNotFoundError = PersonaNotFoundError;
+class UnknownPersonaToolError extends Error {
+    persona;
+    missing;
+    available;
+    constructor(persona, missing, available) {
+        super(`persona ${persona} asks for tool(s) this lane does not offer: ${missing.join(', ')} — available: ${available.join(', ') || '(none)'}`);
+        this.persona = persona;
+        this.missing = missing;
+        this.available = available;
+        this.name = 'UnknownPersonaToolError';
+    }
+}
+exports.UnknownPersonaToolError = UnknownPersonaToolError;
+class PersonaModelUnresolvedError extends Error {
+    persona;
+    constructor(persona) {
+        super(`no model for this run: persona ${persona} names none and the deployment ` +
+            'carries no default (CODE_TASK_MODEL) — a model this host invented would ' +
+            'be billed and refused by a gateway that never routes it');
+        this.persona = persona;
+        this.name = 'PersonaModelUnresolvedError';
+    }
+}
+exports.PersonaModelUnresolvedError = PersonaModelUnresolvedError;
+/** The persona row, or null when the run was given neither an id nor a slug. */
+async function loadPersona(input) {
+    const { client, databaseId, personaId, personaSlug } = input;
+    if (personaId) {
+        const data = await client.request(PERSONA_BY_ID, {
+            id: personaId
+        });
+        if (!data.agentPersona)
+            throw new PersonaNotFoundError(`id ${personaId}`);
+        return data.agentPersona;
+    }
+    if (personaSlug) {
+        const data = await client.request(PERSONA_BY_SLUG, { databaseId, slug: personaSlug });
+        const persona = data.agentPersonas?.nodes?.[0];
+        if (!persona)
+            throw new PersonaNotFoundError(`slug ${personaSlug}`);
+        return persona;
+    }
+    return null;
+}
+/** The `agent_resource` rows a persona names, in the order it named them. */
+async function loadPersonaSkills(input) {
+    const slugs = (input.persona.resources ?? []).filter((slug) => Boolean(slug));
+    if (slugs.length === 0)
+        return [];
+    const data = await input.client.request(RESOURCES_BY_SLUG, { databaseId: input.databaseId, slugs });
+    const found = new Map((data.agentResources?.nodes ?? []).map((row) => [row.slug, row]));
+    const missing = slugs.filter((slug) => !found.has(slug));
+    if (missing.length > 0) {
+        throw new Error(`persona ${input.persona.slug} names agent_resource slug(s) that are absent or inactive: ${missing.join(', ')}`);
+    }
+    return slugs.map((slug) => found.get(slug));
+}
+/**
+ * Resolve what the run should be configured with. Skill bodies are appended to
+ * the prompt — the harness's skill overlay materializes files for hosts that
+ * have a filesystem contract with the model; here the prompt is the contract.
+ */
+function selectPersona(input) {
+    const { persona, availableToolNames, defaultModel, defaultSystemPrompt } = input;
+    const config = persona?.config ?? {};
+    const skills = input.skills ?? [];
+    const requested = config.tools;
+    if (requested) {
+        const missing = requested.filter((name) => !availableToolNames.includes(name));
+        if (missing.length > 0) {
+            throw new UnknownPersonaToolError(persona?.slug ?? '(none)', missing, availableToolNames);
+        }
+    }
+    const excluded = new Set(config.excludeTools ?? []);
+    const toolNames = (requested ?? availableToolNames).filter((name) => !excluded.has(name));
+    const model = config.model ?? defaultModel;
+    if (!model)
+        throw new PersonaModelUnresolvedError(persona?.slug ?? '(none)');
+    const base = persona?.systemPrompt?.trim() || defaultSystemPrompt;
+    const systemPrompt = [base, ...skills.map((skill) => `## ${skill.title}\n\n${skill.body.trim()}`)]
+        .filter(Boolean)
+        .join('\n\n');
+    return {
+        personaId: persona?.id ?? null,
+        model,
+        systemPrompt,
+        ...(config.temperature === undefined ? {} : { temperature: config.temperature }),
+        ...(config.maxSteps === undefined ? {} : { maxSteps: config.maxSteps }),
+        toolNames,
+        skills
+    };
+}

package/project-context.d.ts

@@ -0,0 +1,22 @@
+export interface ProjectContextRequest {
+    /** Where the `.env` is written. Must be outside `workTree`. */
+    dir: string;
+    /** The git clone the agent edits. */
+    workTree: string;
+    databaseId: string;
+    accessToken: string;
+    /** Written as `DATABASE_NAME`, which the record tools need. */
+    databaseName?: string;
+}
+export declare class ProjectContextInsideWorkTreeError extends Error {
+    readonly dir: string;
+    readonly workTree: string;
+    constructor(dir: string, workTree: string);
+}
+/** True when `child` is `parent` or sits beneath it. */
+export declare function isInside(parent: string, child: string): boolean;
+/**
+ * Materialize a pi project context outside the work tree and return its
+ * directory, which is what the control-plane tools take as their cwd.
+ */
+export declare function materializeProjectContext(request: ProjectContextRequest): Promise<string>;

package/project-context.js

@@ -0,0 +1,59 @@
+"use strict";
+// The cwd decision, made explicit.
+//
+// `@agentic-kit/pi`'s control-plane tools resolve their tenant through
+// `resolveProjectContext(cwd)`, which reads `<cwd>/.env` for `ACCESS_TOKEN` and
+// `DATABASE_ID`. In a Job the cwd is a git clone of someone's repository, and
+// writing platform credentials into a work tree the agent is about to `git add`
+// is a credential leak one `git add -A` away — so the coding lane never
+// establishes project context in the clone.
+//
+// It is still legitimate to want both lanes in one run (edit the repo *and*
+// change the schema), so the context is materialized in a directory beside the
+// clone and handed to the tools as their cwd. This module owns that directory
+// and refuses to create it anywhere inside the work tree.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectContextInsideWorkTreeError = void 0;
+exports.isInside = isInside;
+exports.materializeProjectContext = materializeProjectContext;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+class ProjectContextInsideWorkTreeError extends Error {
+    dir;
+    workTree;
+    constructor(dir, workTree) {
+        super(`refusing to write project credentials to ${dir}: it is inside the work tree ${workTree}, where a commit would publish them`);
+        this.dir = dir;
+        this.workTree = workTree;
+        this.name = 'ProjectContextInsideWorkTreeError';
+    }
+}
+exports.ProjectContextInsideWorkTreeError = ProjectContextInsideWorkTreeError;
+/** True when `child` is `parent` or sits beneath it. */
+function isInside(parent, child) {
+    const rel = node_path_1.default.relative(node_path_1.default.resolve(parent), node_path_1.default.resolve(child));
+    return rel === '' || (!rel.startsWith('..') && !node_path_1.default.isAbsolute(rel));
+}
+/**
+ * Materialize a pi project context outside the work tree and return its
+ * directory, which is what the control-plane tools take as their cwd.
+ */
+async function materializeProjectContext(request) {
+    if (isInside(request.workTree, request.dir)) {
+        throw new ProjectContextInsideWorkTreeError(request.dir, request.workTree);
+    }
+    if (!request.databaseId || !request.accessToken) {
+        throw new Error('a project context needs both DATABASE_ID and ACCESS_TOKEN');
+    }
+    await (0, promises_1.mkdir)(request.dir, { recursive: true, mode: 0o700 });
+    const lines = [
+        `DATABASE_ID=${request.databaseId}`,
+        `ACCESS_TOKEN=${request.accessToken}`,
+        ...(request.databaseName ? [`DATABASE_NAME=${request.databaseName}`] : [])
+    ];
+    await (0, promises_1.writeFile)(node_path_1.default.join(request.dir, '.env'), `${lines.join('\n')}\n`, { mode: 0o600 });
+    return request.dir;
+}

package/tools.d.ts

@@ -0,0 +1,23 @@
+import type { AgentTool } from '@agentic-kit/agent';
+import type { ConfirmGate, ConfirmGateDeps, GateHost } from '@agentic-kit/harness';
+export interface GatedToolsetOptions {
+    tools: AgentTool[];
+    host: GateHost;
+    /** The directory the gate's project checks are about. */
+    cwd: string;
+    /** Supply a gate to test against; defaults to the harness's. */
+    gate?: ConfirmGate;
+    /**
+     * The harness gate's project questions. A coding lane whose cwd is a git
+     * clone answers "not a Constructive project" — see `project-context.ts`.
+     */
+    deps?: ConfirmGateDeps;
+}
+export interface GatedToolset {
+    tools: AgentTool[];
+    /** Call before each run: clears the decline memory. */
+    onAgentStart: () => void;
+}
+/** The gate's deps for a workspace that is a git clone, not a Constructive project. */
+export declare const CLONE_GATE_DEPS: ConfirmGateDeps;
+export declare function createGatedToolset(options: GatedToolsetOptions): GatedToolset;

package/tools.js

@@ -0,0 +1,36 @@
+"use strict";
+// Putting the harness gate in front of the agent's tools.
+//
+// `createConfirmGate` is the harness's, unchanged: it decides which tools are
+// gated (`MUTATING_DB_TOOLS`), writes the prompt, and remembers declines so a
+// retry is skipped rather than re-asked. All this adds is the seam — the gate
+// runs inside `execute`, and a blocked call returns the gate's reason to the
+// model as an ordinary tool result, which is how the model learns it was
+// declined.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLONE_GATE_DEPS = void 0;
+exports.createGatedToolset = createGatedToolset;
+const harness_1 = require("@agentic-kit/harness");
+/** The gate's deps for a workspace that is a git clone, not a Constructive project. */
+exports.CLONE_GATE_DEPS = {
+    isProjectRunnable: async () => false,
+    hasDataToken: async () => false,
+    resolveTemplatePreview: async () => undefined
+};
+function createGatedToolset(options) {
+    const gate = options.gate ?? (0, harness_1.createConfirmGate)(options.deps ?? exports.CLONE_GATE_DEPS);
+    const { host, cwd } = options;
+    const tools = options.tools.map((tool) => ({
+        ...tool,
+        execute: async (toolCallId, params, decision, signal, onUpdate) => {
+            const blocked = await gate.onToolCall({ toolName: tool.name, toolCallId, input: params }, host, cwd);
+            if (blocked)
+                return blockedResult(blocked.reason);
+            return tool.execute(toolCallId, params, decision, signal, onUpdate);
+        }
+    }));
+    return { tools, onAgentStart: gate.onAgentStart };
+}
+function blockedResult(reason) {
+    return { content: [{ type: 'text', text: reason }] };
+}