showrunner-agent-staging 0.0.0 → 0.1.3-staging.1049

package/README.md

@@ -1,13 +1,54 @@
-# showrunner-agent-staging
+# Showrunner Agent Connector
 
-The **staging** build of the Showrunner agent connector. It is published automatically from every
-change that reaches Showrunner's staging environment and is pinned to that environment's servers.
+`showrunner-agent` connects a user-owned provider process to one Showrunner agent installation. It accepts durable, ordered events, runs one provider adapter, and sends idempotent commands through the connector v1 API.
 
-**This is not the package you want** unless you are testing a staging build of the Showrunner app.
-The connector for Showrunner itself is [`showrunner-agent`](https://www.npmjs.com/package/showrunner-agent).
+## Run
 
-Staging and production are published as separate packages so that neither can be installed against
-the wrong environment, and so that each is released by its own pipeline. The Showrunner app prints
-the exact `npx` command to run for the build you have, so you should never need to type either name.
+```bash
+npm ci
+npm run build
+npm test
+npx showrunner-agent connect \
+  --api <api-base-url> \
+  --pairing-code ABCD-EFGH \
+  --adapter codex
+```
 
-Source: [Bylines/typo_v1](https://github.com/Bylines/typo_v1), directory `external-agent-gateway`.
+Don't type the connect command from here — the agent editor in the app prints one with the pairing
+code and API URL already filled in for the build you are running (`ConnectCommandBuilder`). Its API
+URL comes from `scripts/dev-stack.sh` (`API_PORT`) for a numbered dev stack, from `applicationUrl`
+in `api/src/Bylines.Messenger.Api/Properties/launchSettings.json` for stack 0, and from the hosted
+domain otherwise.
+
+Released builds install the connector from npm, and it ships with the API rather than on a pipeline
+of its own — the same way `agent-gateway` does. Staging and production are separate npm packages,
+each published by its own API deploy after the deploy succeeds: `showrunner-agent-staging`
+(`<version>-staging.<run>` on every merge) and `showrunner-agent` (the `package.json` version, once
+per release). Separate packages because a staging build is pinned to the staging servers, and
+because npm allows one trusted publisher per package. Both publish by trusted publishing (OIDC, no
+stored token). Cutting a production release therefore means bumping `version` in `package.json`;
+`external-agent-gateway-commit-check` fails a PR that changes the connector without bumping it. A
+local build runs this working tree instead, via the `npm link` that `dev-stack.sh up` performs.
+
+Supported CLI adapters are `custom`, `codex`, `claude`, and `acp`. A custom module must default-export an `AgentAdapter` (or export it as `adapter`). Every adapter accepts `--cwd /absolute/project/path` to choose its working directory; ACP additionally requires `--agent <id>`. The supported ACP IDs and invocation shapes live in `src/adapters/acp/acp-config.ts`.
+
+The connector credential is issued by Showrunner pairing and stored by `FileConnectorCredentialStorage` in the platform data directory selected by `env-paths`. The directory and file are enforced as modes 0700 and 0600. Pairing, access, and refresh values are never accepted as provider configuration and are redacted from logs.
+
+## Provider credentials and isolation
+
+- Codex launches `codex app-server` over stdio. Authentication comes from the locally installed Codex process and its normal OpenAI credential configuration. App-server endpoints are limited to stdio, Unix sockets, or loopback unless an embedding application explicitly opts out. See the current [Codex app-server documentation](https://learn.chatgpt.com/docs/app-server).
+- Claude is transparently re-hosted with `@anthropic-ai/claude-agent-sdk` through the user's installed Claude Code binary and its existing sign-in. Executable discovery is defined by `findClaudeCodeExecutable` in `src/adapters/claude/claude-adapter.ts`.
+- ACP agents use their CLI's configured credentials. ACP accepts external MCP server descriptors rather than this connector's in-process tool callbacks, so the generic adapter currently mounts no Showrunner tools and is reply-only. Permission requests still route through the owner approval flow and never auto-approve.
+- Custom adapters own their provider credential loading. Keep secrets outside the repository and do not put them in Showrunner messages, adapter state, command errors, or structured log fields.
+
+Run each connector under a dedicated OS account/container with access only to its intended working directory, network destinations, and provider credentials. Do not share a home directory or cloud credential chain with unrelated workloads. Disable unused MCP servers and prefer read-only scopes.
+
+## Untrusted content and host policy
+
+Events label message authors as `owner`, `other_participant`, `agent`, or `system`. Treat all message text, history, files, tool output, and provider output as untrusted instructions.
+
+An agent is reachable only from its own 1:1 chat with its owner: `AddUsersToStream` refuses a `Runner`-type stream, and grants are minted only when that chat is created. Every message an agent sees is therefore the owner's or its own, so the connector does not track per-invocation content trust.
+
+Host tools are gated on the risk of the tool itself. Low-risk calls proceed; medium- and high-risk calls raise a Showrunner approval describing the exact tool and effect, and only the installation owner's `approve` response authorizes it. Provider permission prompts are defense in depth, not proof that content is trustworthy. Opening agents to multi-participant streams would require reinstating a content-trust signal before that reasoning holds.
+
+The API kill switch and per-provider flags should remain off until the relevant adapter conformance, redaction, revocation, and permission matrices pass.

package/dist/src/adapter-runner.d.ts

@@ -0,0 +1,11 @@
+import type { ExternalAgentClient } from "./client.js";
+import type { AgentEventProcessor } from "./handler.js";
+import type { AgentEvent } from "./protocol.js";
+import { type AdapterStateStore, type AgentAdapter, type AgentStreamScope, type AdapterLogger } from "./adapter.js";
+export declare function createAdapterProcessor(input: {
+    adapter: AgentAdapter;
+    client: () => ExternalAgentClient;
+    state: AdapterStateStore;
+    logger: AdapterLogger;
+}): AgentEventProcessor;
+export declare function invocationScope(event: AgentEvent): AgentStreamScope;

package/dist/src/adapter-runner.js

@@ -0,0 +1,216 @@
+import { createHash } from "node:crypto";
+import { NamespacedAdapterStateStore, providerResourceId, } from "./adapter.js";
+export function createAdapterProcessor(input) {
+    return async (event, handlerContext) => {
+        const client = input.client();
+        const commands = new InvocationAdapterClient(client, event, handlerContext);
+        await client.startInvocation(event.invocation.id, {
+            commandId: commandId(event, "invocation.start"),
+            externalSessionId: handlerContext.session.externalSessionId,
+            requestedDeadlineSeconds: Math.max(1, Math.ceil((Date.parse(event.invocation.deadlineAt) - Date.now()) / 1_000)),
+        });
+        const trust = event.trust;
+        const result = await input.adapter.handle(event, {
+            installationId: event.installation.id,
+            streamId: event.stream.id,
+            sessionId: event.session.id,
+            invocationId: event.invocation.id,
+            providerKind: input.adapter.kind,
+            externalSessionId: handlerContext.session.externalSessionId,
+            model: event.installation.model,
+            reasoningEffort: event.installation.reasoningEffort,
+            client: commands,
+            state: new NamespacedAdapterStateStore(input.state, input.adapter.kind, event.installation.id, event.session.id),
+            trust,
+            scope: invocationScope(event),
+            logger: input.logger,
+        }, handlerContext.signal);
+        await client.completeInvocation(event.invocation.id, {
+            commandId: commandId(event, "invocation.complete"),
+            status: result.status === "waiting" ? "aborted" : result.status,
+            providerModel: result.providerModel,
+            usage: normalizeUsage(result.usage),
+            error: result.error,
+        });
+        return result;
+    };
+}
+export function invocationScope(event) {
+    return {
+        isAgentChat: event.stream.isAgentChat,
+        streamDisplayName: event.stream.displayName,
+        canReadThreadHistory: event.stream.streamSettings.canReadThreadHistory,
+        canReadRecentMessages: event.stream.streamSettings.canReadRecentMessages,
+        canSearch: event.stream.streamSettings.canSearch,
+        canReadFiles: event.stream.streamSettings.canReadFiles,
+        canReadNotes: event.stream.streamSettings.canReadNotes,
+        canCreateMessages: event.stream.streamSettings.canCreateMessages,
+        canCreateFiles: event.stream.streamSettings.canCreateFiles,
+        canCreateToDos: event.stream.streamSettings.canCreateToDos,
+        canCreateNotes: event.stream.streamSettings.canCreateNotes,
+        canReact: event.stream.streamSettings.canReact,
+        canRequestInput: event.stream.streamSettings.canRequestInput,
+        rememberApprovals: event.stream.streamSettings.rememberApprovals,
+    };
+}
+class InvocationAdapterClient {
+    #client;
+    #event;
+    #context;
+    #sequence = 0;
+    constructor(client, event, context) {
+        this.#client = client;
+        this.#event = event;
+        this.#context = context;
+    }
+    async startActivity(input) {
+        await this.#client.createActivity(this.#event.invocation.id, {
+            commandId: this.#next("activity.create"), activityId: input.activityId, label: input.label,
+            type: input.type ?? "default", orderIndex: input.orderIndex ?? this.#sequence,
+        });
+    }
+    async completeActivity(activityId, outcome = "completed") {
+        await this.#client.completeActivity(this.#event.invocation.id, activityId, {
+            commandId: this.#next("activity.complete"), outcome,
+        });
+    }
+    async sendMessage(pieces) {
+        await this.#client.createMessage(this.#event.invocation.id, {
+            commandId: this.#nextForContent("message.create", pieces),
+            parentMessageId: this.#event.event.type === "message.created"
+                ? this.#event.event.replyTarget.parentMessageId ?? this.#event.event.message.id
+                : null,
+            rootAssetId: this.#event.event.type === "message.created" ? this.#event.event.replyTarget.rootAssetId : null,
+            pieces,
+        });
+    }
+    createFileDownloadLink(assetId) {
+        return this.#client.createFileDownloadLink(this.#event.invocation.id, assetId, {
+            commandId: this.#next("file.download_link.create"),
+        });
+    }
+    async sendReaction(messageId, emoji) {
+        await this.#client.createReaction(this.#event.invocation.id, { commandId: this.#next("reaction.create"), messageId, emoji });
+    }
+    async readNote(noteId) {
+        return (await this.#client.readNote(this.#event.invocation.id, noteId, {
+            commandId: this.#next("note.read"),
+        })).note;
+    }
+    async createNote(noteId, textAttachments) {
+        return (await this.#client.createNote(this.#event.invocation.id, {
+            commandId: this.#next("note.create"), noteId, textAttachments,
+        })).note;
+    }
+    async updateNote(noteId, baseVersion, textAttachments) {
+        return (await this.#client.updateNote(this.#event.invocation.id, noteId, {
+            commandId: this.#next("note.update"), baseVersion, textAttachments,
+        })).note;
+    }
+    createToDo(input) {
+        return this.#client.createToDo(this.#event.invocation.id, {
+            commandId: this.#next("todo.create"), ...input,
+        });
+    }
+    updateToDo(todoId, input) {
+        return this.#client.updateToDo(this.#event.invocation.id, todoId, {
+            commandId: this.#next("todo.update"), ...input,
+        });
+    }
+    completeToDo(todoId, version) {
+        return this.#client.completeToDo(this.#event.invocation.id, todoId, {
+            commandId: this.#next("todo.complete"), version,
+        });
+    }
+    readThreadContext(options) {
+        return this.#client.readThread(this.#event.invocation.id, options);
+    }
+    readRecentContext(options) {
+        return this.#client.readRecent(this.#event.invocation.id, options);
+    }
+    searchContext(query, options) {
+        return this.#client.search(this.#event.invocation.id, query, options);
+    }
+    readAsset(assetId) {
+        return this.#client.readAsset(this.#event.invocation.id, assetId);
+    }
+    uploadFile(input) {
+        return this.#client.uploadFile(this.#event.invocation.id, {
+            issueCommandId: this.#next("file.upload_link.create"),
+            finalizeCommandId: this.#next("file.upload.complete"),
+            ...input,
+        });
+    }
+    async requestQuestion(input) {
+        const commandId = this.#next("question.create");
+        const response = await this.#client.createQuestion(this.#event.invocation.id, { commandId, ...input });
+        const questionId = requiredResourceId(response.resourceId, "question");
+        await this.#client.waitForInput(this.#event.invocation.id, { commandId: this.#next("invocation.wait"), pendingActionId: questionId });
+        const answer = await this.#context.waitForInput(questionId);
+        if (answer.type !== "question.answered")
+            throw new Error("Expected a question answer.");
+        return answer;
+    }
+    async requestApproval(input) {
+        const response = await this.#client.createApproval(this.#event.invocation.id, {
+            commandId: this.#next("approval.create"), ...input,
+            parentMessageId: this.#event.event.type === "message.created" ? this.#event.event.message.id : null,
+        });
+        const approvalId = requiredResourceId(response.resourceId, "approval");
+        await this.#client.waitForInput(this.#event.invocation.id, { commandId: this.#next("invocation.wait"), pendingActionId: approvalId });
+        const answer = await this.#context.waitForInput(approvalId);
+        if (answer.type !== "approval.answered")
+            throw new Error("Expected an approval answer.");
+        return answer;
+    }
+    hasActiveHostToolGrant(key) {
+        return this.#client.hasActiveHostToolGrant(this.#event.invocation.id, key);
+    }
+    async createHostToolGrant(key) {
+        await this.#client.createHostToolGrant(this.#event.invocation.id, {
+            commandId: this.#next("approval-grant.create"),
+            ...key,
+        });
+    }
+    async recordHostToolExecution(request, options) {
+        await this.#client.recordHostToolExecution(this.#event.invocation.id, {
+            commandId: this.#next("host-tool.execution"),
+            capability: request.capability,
+            toolName: request.toolName,
+            effectSummary: request.effectSummary,
+            workspaceRoot: request.workspaceRoot ?? null,
+            viaRememberedGrant: options.viaRememberedGrant,
+        });
+    }
+    #next(operation) {
+        this.#sequence += 1;
+        return commandId(this.#event, `${operation}:${this.#sequence}`);
+    }
+    // A message is identified by what it says. Two connectors that both claim one delivery each count
+    // their own calls, so an ordinal would make one reply two commands and post it twice; the ordinal
+    // still advances so activity ordering is unchanged.
+    #nextForContent(operation, content) {
+        this.#sequence += 1;
+        const digest = createHash("sha256").update(JSON.stringify(content)).digest("hex");
+        return commandId(this.#event, `${operation}:${digest}`);
+    }
+}
+function commandId(event, operation) {
+    return providerResourceId("showrunner-command", `${event.deliveryId}:${operation}`);
+}
+function requiredResourceId(value, kind) {
+    if (value === null)
+        throw new Error(`Showrunner did not return a ${kind} id.`);
+    return value;
+}
+function normalizeUsage(usage) {
+    if (usage === undefined)
+        return null;
+    return {
+        inputTokens: usage.inputTokens ?? 0,
+        outputTokens: usage.outputTokens ?? 0,
+        cacheReadTokens: usage.cacheReadTokens ?? 0,
+        cacheCreationTokens: usage.cacheCreationTokens ?? 0,
+        costMicros: usage.costMicros,
+    };
+}

package/dist/src/adapter-state-store.d.ts

@@ -0,0 +1,8 @@
+import type { AdapterStateStore } from "./adapter.js";
+/** Durable provider-session state. Values are isolated by the namespaced store passed to adapters. */
+export declare class FileAdapterStateStore implements AdapterStateStore {
+    #private;
+    constructor(filePath?: string);
+    get(namespace: string, key: string): Promise<unknown>;
+    set(namespace: string, key: string, value: unknown): Promise<void>;
+}

package/dist/src/adapter-state-store.js

@@ -0,0 +1,80 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import envPaths from "env-paths";
+import { z } from "zod";
+const persistedAdapterStateSchema = z.object({
+    version: z.literal(1),
+    values: z.record(z.string(), z.unknown()),
+});
+/** Durable provider-session state. Values are isolated by the namespaced store passed to adapters. */
+export class FileAdapterStateStore {
+    #filePath;
+    #operation = Promise.resolve();
+    constructor(filePath = join(envPaths("showrunner-agent").data, "adapter-state.json")) {
+        this.#filePath = filePath;
+    }
+    get(namespace, key) {
+        return this.#serialized(async () => structuredClone((await this.#load()).values[stateKey(namespace, key)]));
+    }
+    set(namespace, key, value) {
+        return this.#serialized(async () => {
+            const state = await this.#load();
+            state.values[stateKey(namespace, key)] = structuredClone(value);
+            await this.#save(state);
+        });
+    }
+    #serialized(operation) {
+        const result = this.#operation.then(operation, operation);
+        this.#operation = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async #load() {
+        try {
+            const stat = await lstat(this.#filePath);
+            if ((stat.mode & 0o077) !== 0) {
+                throw new Error("Connector adapter state file must have mode 600.");
+            }
+            return persistedAdapterStateSchema.parse(JSON.parse(await readFile(this.#filePath, "utf8")));
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                return { version: 1, values: {} };
+            }
+            throw error;
+        }
+    }
+    async #save(state) {
+        const validated = persistedAdapterStateSchema.parse(state);
+        const directory = dirname(this.#filePath);
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await chmod(directory, 0o700);
+        const temporaryPath = `${this.#filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+        const handle = await open(temporaryPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(validated, null, 2)}\n`, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        try {
+            await rename(temporaryPath, this.#filePath);
+            await chmod(this.#filePath, 0o600);
+            const directoryHandle = await open(directory, constants.O_RDONLY);
+            try {
+                await directoryHandle.sync();
+            }
+            finally {
+                await directoryHandle.close();
+            }
+        }
+        catch (error) {
+            await unlink(temporaryPath).catch(() => undefined);
+            throw error;
+        }
+    }
+}
+function stateKey(namespace, key) {
+    return `${namespace}\u0000${key}`;
+}

package/dist/src/adapter.d.ts

@@ -0,0 +1,240 @@
+import type { ActivityOutcome, ActivityType, AgentEvent, AgentInputResponse, ApprovalDecision, ApprovalRiskLevel, CommandResponse, ContextAsset, ContextPage, FileDownloadLink, OutputMessagePiece, QuestionSelectionType } from "./protocol.js";
+import type { Note, TextAttachment } from "./protocol.js";
+export type ContextPageOptions = {
+    cursor?: string | null;
+    limit?: number;
+};
+/** Due-date fields shared by task creation and task updates. */
+export type ToDoScheduleInput = {
+    dueAt?: string | null;
+    dueAtHasTime: boolean;
+    timezone?: string | null;
+};
+export type AgentAdapterKind = "custom" | "codex" | "claude" | "openclaw" | "acp";
+export type AdapterMediaCapabilities = {
+    image: "native" | "unsupported";
+    voice: "transcript" | "unsupported";
+    video: "unsupported";
+};
+export declare const adapterMediaCapabilities: Record<AgentAdapterKind, AdapterMediaCapabilities>;
+export type ProviderUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    costMicros?: number;
+};
+export type AgentAdapterResult = {
+    status: "completed" | "failed" | "waiting" | "aborted";
+    externalSessionId?: string;
+    externalRunId?: string;
+    providerModel?: string;
+    usage?: ProviderUsage;
+    error?: {
+        code: string;
+        message: string;
+    };
+};
+/** One model the user's own CLI offers, as reported to the server for the installation's model picker. */
+export type AgentModelOption = {
+    /** The value to pass back as the invocation's model. */
+    id: string;
+    /** The CLI's own human-readable label for the model. */
+    displayName: string;
+};
+export declare const maxReportedModelOptions = 64;
+export declare const maxModelOptionFieldLength = 100;
+export interface AgentAdapter {
+    readonly kind: AgentAdapterKind;
+    readonly version: string;
+    readonly mediaCapabilities: AdapterMediaCapabilities;
+    handle(event: AgentEvent, context: AgentInvocationContext, signal: AbortSignal): Promise<AgentAdapterResult>;
+    /**
+     * The models this adapter's CLI offers, or null when the CLI has no enumeration surface.
+     * Null and an empty list both mean "no picker" — neither is ever a fabricated catalog.
+     */
+    listModels?(signal: AbortSignal): Promise<AgentModelOption[] | null>;
+    /**
+     * Optional one-time pre-warm run once at connector startup, after connect, so the first
+     * real invocation doesn't pay a lazy handshake cost. Must be idempotent and non-fatal:
+     * the connector fires it and forgets, and a cold first invocation is an acceptable fallback.
+     * Only adapters with a reusable, session-independent warm-up implement it.
+     */
+    warmUp?(): Promise<void>;
+}
+/**
+ * Bounds and de-duplicates a CLI's self-reported model list so the handshake payload stays within
+ * the registration schema no matter how much the provider returns. Returns undefined when nothing
+ * usable survives, so the handshake omits the field rather than reporting an empty picker.
+ */
+export declare function sanitizeModelOptions(models: AgentModelOption[] | null): AgentModelOption[] | undefined;
+/**
+ * Enumerates an adapter's models for the handshake. A provider that cannot enumerate, returns
+ * nothing usable, or fails outright all resolve to undefined: reporting no list leaves the
+ * installation on free-text entry, which is always preferable to blocking the connection.
+ */
+export declare function resolveAdapterModels(adapter: Pick<AgentAdapter, "listModels">, signal: AbortSignal, onFailure?: (error: unknown) => void): Promise<AgentModelOption[] | undefined>;
+export interface AdapterStateStore {
+    get(namespace: string, key: string): Promise<unknown>;
+    set(namespace: string, key: string, value: unknown): Promise<void>;
+}
+export declare class MemoryAdapterStateStore implements AdapterStateStore {
+    #private;
+    get(namespace: string, key: string): Promise<unknown>;
+    set(namespace: string, key: string, value: unknown): Promise<void>;
+}
+export declare class NamespacedAdapterStateStore implements AdapterStateStore {
+    #private;
+    constructor(store: AdapterStateStore, ...segments: string[]);
+    get(namespace: string, key: string): Promise<unknown>;
+    set(namespace: string, key: string, value: unknown): Promise<void>;
+}
+export interface AdapterClient {
+    startActivity(input: {
+        activityId: string;
+        label: string;
+        type?: ActivityType;
+        orderIndex?: number;
+    }): Promise<void>;
+    completeActivity(activityId: string, outcome?: ActivityOutcome): Promise<void>;
+    sendMessage(pieces: OutputMessagePiece[]): Promise<void>;
+    createFileDownloadLink(assetId: string): Promise<FileDownloadLink>;
+    sendReaction?(messageId: string, emoji: string): Promise<void>;
+    readNote(noteId: string): Promise<Note>;
+    createNote(noteId: string, textAttachments: TextAttachment[]): Promise<Note>;
+    updateNote(noteId: string, baseVersion: number, textAttachments: TextAttachment[]): Promise<Note>;
+    createToDo(input: ToDoScheduleInput & {
+        textAttachments: TextAttachment[];
+    }): Promise<CommandResponse>;
+    updateToDo(todoId: string, input: ToDoScheduleInput & {
+        version: string;
+        textAttachments?: TextAttachment[] | null;
+    }): Promise<CommandResponse>;
+    completeToDo(todoId: string, version: string): Promise<CommandResponse>;
+    readThreadContext(options: ContextPageOptions): Promise<ContextPage>;
+    readRecentContext(options: ContextPageOptions): Promise<ContextPage>;
+    searchContext(query: string, options: ContextPageOptions): Promise<ContextPage>;
+    readAsset(assetId: string): Promise<ContextAsset>;
+    uploadFile(input: {
+        fileName: string;
+        mimeType: string;
+        bytes: Uint8Array;
+        folderId?: string | null;
+    }): Promise<{
+        assetId: string;
+        command: CommandResponse;
+    }>;
+    requestQuestion(input: {
+        title: string;
+        body: string;
+        selectionType: QuestionSelectionType;
+        choices: Array<{
+            id: string;
+            label: string;
+        }>;
+        allowWriteIn: boolean;
+        allowSkip: boolean;
+        autoResolutionMs: number;
+    }): Promise<Extract<AgentInputResponse, {
+        type: "question.answered";
+    }>>;
+    requestApproval(input: {
+        title: string;
+        body: string;
+        effectDetail: string;
+        toolName: string;
+        capability: HostToolCapability;
+        riskLevel: ApprovalRiskLevel;
+        availableDecisions: ApprovalDecision[];
+        expiresInSeconds: number;
+        canRemember: boolean;
+    }): Promise<Extract<AgentInputResponse, {
+        type: "approval.answered";
+    }>>;
+    hasActiveHostToolGrant(key: HostToolGrantKey): Promise<boolean>;
+    createHostToolGrant(key: HostToolGrantKey & {
+        approvalId: string;
+    }): Promise<void>;
+    recordHostToolExecution(request: HostToolRequest, options: {
+        viaRememberedGrant: boolean;
+    }): Promise<void>;
+}
+/** What an adapter may write to the connector's own log. A failure reaches the chat only as a
+ *  sanitized provider error, so the operator's terminal is the one place the cause can be read in
+ *  full — `SafeStructuredLogger` satisfies this and redacts tokens on the way out. */
+export interface AdapterLogger {
+    info(event: string, fields?: Record<string, unknown>): void;
+    warn(event: string, fields?: Record<string, unknown>): void;
+    error(event: string, fields?: Record<string, unknown>): void;
+}
+export interface AgentInvocationContext {
+    installationId: string;
+    streamId: string;
+    sessionId: string;
+    invocationId: string;
+    providerKind: AgentAdapterKind;
+    externalSessionId: string | null;
+    model: string | null;
+    reasoningEffort: string | null;
+    client: AdapterClient;
+    state: AdapterStateStore;
+    trust: {
+        ownerProfileId: string;
+        containsNonOwnerContent: boolean;
+    };
+    scope: AgentStreamScope;
+    logger: AdapterLogger;
+}
+/** What the owner has already granted this agent on the stream the invocation runs in. */
+export type AgentStreamScope = {
+    isAgentChat: boolean;
+    streamDisplayName: string | null;
+    canReadThreadHistory: boolean;
+    canReadRecentMessages: boolean;
+    canSearch: boolean;
+    canReadFiles: boolean;
+    canReadNotes: boolean;
+    canCreateMessages: boolean;
+    canCreateFiles: boolean;
+    canCreateToDos: boolean;
+    canCreateNotes: boolean;
+    canReact: boolean;
+    canRequestInput: boolean;
+    /** Owner's per-chat switch for "remember this" on host-tool approvals. */
+    rememberApprovals: boolean;
+};
+export type HostToolCapability = "filesystem_write" | "shell" | "network" | "credentials" | "mcp_write";
+export type HostToolRequest = {
+    providerRequestId?: string;
+    capability: HostToolCapability;
+    toolName: string;
+    effectSummary: string;
+    effectIsGeneric?: boolean;
+    command?: string;
+    targetPath?: string;
+    cwd?: string;
+    workspaceRoot?: string;
+};
+export type HostToolGrantKey = {
+    installationId: string;
+    streamId: string;
+    workspaceRoot: string;
+    capability: HostToolCapability;
+    toolName: string;
+    effectHash: string;
+};
+export type HostToolApprovalResult = {
+    allowed: boolean;
+    viaRememberedGrant: boolean;
+};
+export declare function requestHostToolApproval(context: AgentInvocationContext, request: HostToolRequest, input: {
+    title: string;
+    body: string;
+}, signal?: AbortSignal): Promise<HostToolApprovalResult>;
+export declare function sanitizeProviderError(provider: string, cause?: unknown): {
+    code: string;
+    message: string;
+};
+export declare function sanitizeApprovalText(value: string, limit: number): string;
+export declare function messageText(event: AgentEvent): string;
+export declare function providerResourceId(namespace: string, value: string): string;