@agentic-kit/pi-host 0.2.0

package/esm/model.js

@@ -0,0 +1,211 @@
+// 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.
+import { calculateUsageCost, createAssistantMessage, createAssistantMessageEventStream, createToolCall, OpenAIAdapter } from '@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.
+ */
+export 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.
+ */
+export function gatewayApiRoot(agenticServerUrl) {
+    return `${agenticServerUrl.replace(/\/+$/, '').replace(/\/v1$/, '')}/v1`;
+}
+export 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 OpenAIAdapter({
+        baseUrl: apiRoot,
+        provider: 'agentic-server',
+        headers
+    });
+    const streamFn = (descriptor, context, streamOptions) => {
+        const stream = createAssistantMessageEventStream();
+        void (async () => {
+            const message = 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);
+    calculateUsageCost(descriptor, message.usage);
+    return calls > 0;
+}
+function toToolCall(raw, index) {
+    const toolCall = 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/esm/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/esm/persona.js

@@ -0,0 +1,122 @@
+// 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.
+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 } }
+}`;
+export class PersonaNotFoundError extends Error {
+    ref;
+    constructor(ref) {
+        super(`no active agent persona for ${ref}`);
+        this.ref = ref;
+        this.name = 'PersonaNotFoundError';
+    }
+}
+export 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';
+    }
+}
+export 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';
+    }
+}
+/** The persona row, or null when the run was given neither an id nor a slug. */
+export 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. */
+export 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.
+ */
+export 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/esm/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/esm/project-context.js

@@ -0,0 +1,50 @@
+// 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.
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export 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';
+    }
+}
+/** True when `child` is `parent` or sits beneath it. */
+export function isInside(parent, child) {
+    const rel = path.relative(path.resolve(parent), path.resolve(child));
+    return rel === '' || (!rel.startsWith('..') && !path.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.
+ */
+export 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 mkdir(request.dir, { recursive: true, mode: 0o700 });
+    const lines = [
+        `DATABASE_ID=${request.databaseId}`,
+        `ACCESS_TOKEN=${request.accessToken}`,
+        ...(request.databaseName ? [`DATABASE_NAME=${request.databaseName}`] : [])
+    ];
+    await writeFile(path.join(request.dir, '.env'), `${lines.join('\n')}\n`, { mode: 0o600 });
+    return request.dir;
+}

package/esm/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/esm/tools.js

@@ -0,0 +1,32 @@
+// 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.
+import { createConfirmGate } from '@agentic-kit/harness';
+/** The gate's deps for a workspace that is a git clone, not a Constructive project. */
+export const CLONE_GATE_DEPS = {
+    isProjectRunnable: async () => false,
+    hasDataToken: async () => false,
+    resolveTemplatePreview: async () => undefined
+};
+export function createGatedToolset(options) {
+    const gate = options.gate ?? createConfirmGate(options.deps ?? 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 }] };
+}

package/esm/workspace-tools.d.ts

@@ -0,0 +1,22 @@
+import type { AgentTool } from '@agentic-kit/agent';
+export declare const DEFAULT_COMMAND_TIMEOUT_MS = 120000;
+export declare const MAX_READ_BYTES = 200000;
+export interface WorkspaceToolsOptions {
+    /** The clone the run edits. Every tool is relative to it. */
+    cwd: string;
+    /** Wall-clock cap for `run_command`. */
+    commandTimeoutMs?: number;
+    /** Environment `run_command` runs with. Defaults to the Job's, minus nothing. */
+    env?: NodeJS.ProcessEnv;
+}
+export declare class OutsideWorkspaceError extends Error {
+    readonly requested: string;
+    readonly cwd: string;
+    constructor(requested: string, cwd: string);
+}
+/**
+ * Read, write, edit, list, run. Named the way pi names them so a persona's
+ * tool allowlist reads the same in either host.
+ */
+export declare function createWorkspaceTools(options: WorkspaceToolsOptions): AgentTool[];
+export declare const WORKSPACE_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "list_files", "run_command"];