@assemblyline-agents/core 0.1.0

package/dist/connection-types.d.ts

@@ -0,0 +1,318 @@
+import type { AdapterDefinition, ApprovalPolicy, JsonObject, JsonSchema, JsonValue, MaybePromise } from "./index.js";
+export interface ConnectionDefinition {
+    description?: string;
+    provider: string;
+    binding?: AdapterDefinition;
+    scopes?: string[];
+    capabilities?: string[];
+    subject?: "user" | "workspace" | "installation" | "environment";
+    required?: boolean;
+    metadata?: JsonObject;
+}
+export type ConnectionProtocol = "declaration" | "mcp" | "openapi" | "http" | "cli";
+export interface TokenResult {
+    token: string;
+    expiresAt?: number;
+    refreshToken?: string;
+    tokenType?: string;
+    scopes?: string[];
+    /** Non-standard token-response extras (provider identity ids etc.). */
+    credential?: JsonObject;
+}
+export type ConnectionPrincipal = {
+    type: "app";
+} | {
+    type: "user";
+    id: string;
+    issuer: string;
+    attributes?: Record<string, string | string[]>;
+};
+export interface ConnectionAuthorizationContext {
+    url: string;
+}
+export interface ConnectionAuthorizationChallenge {
+    url?: string;
+    userCode?: string;
+    instructions?: string;
+    displayName?: string;
+    [key: string]: JsonValue | undefined;
+}
+export interface AuthorizationCallback {
+    params: Record<string, string>;
+    method: string;
+    body?: string;
+}
+export interface NonInteractiveAuthorizationDefinition {
+    principalType: "app" | "user";
+    displayName?: string;
+    getToken(options: {
+        principal: ConnectionPrincipal;
+        connection: ConnectionAuthorizationContext;
+    }): MaybePromise<TokenResult>;
+    evict?(options: {
+        principal: ConnectionPrincipal;
+        connection: ConnectionAuthorizationContext;
+    }): MaybePromise<void>;
+    startAuthorization?: undefined;
+    completeAuthorization?: undefined;
+}
+export interface OAuthAuthorizationDefinition {
+    principalType: "user";
+    displayName?: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    clientId: string;
+    clientSecret?: string;
+    scopes?: string[];
+    redirectUri?: string;
+    authorizationParams?: Record<string, string>;
+    tokenParams?: Record<string, string>;
+    pkce?: boolean;
+    /** Override the token response's scheme when the provider requires a non-Bearer Authorization header. */
+    tokenType?: string;
+}
+export interface InteractiveAuthorizationDefinition<Resume extends JsonValue = JsonValue> {
+    principalType: "user";
+    displayName?: string;
+    getToken(options: {
+        principal: ConnectionPrincipal;
+        connection: ConnectionAuthorizationContext;
+    }): MaybePromise<TokenResult>;
+    evict?(options: {
+        principal: ConnectionPrincipal;
+        connection: ConnectionAuthorizationContext;
+    }): MaybePromise<void>;
+    startAuthorization(options: {
+        principal: ConnectionPrincipal;
+        connection: ConnectionAuthorizationContext;
+        callbackUrl: string;
+    }): MaybePromise<{
+        challenge: ConnectionAuthorizationChallenge;
+        resume?: Resume;
+    }>;
+    completeAuthorization(options: {
+        principal: ConnectionPrincipal;
+        connection: ConnectionAuthorizationContext;
+        callbackUrl: string;
+        resume?: Resume;
+        callback: AuthorizationCallback;
+    }): MaybePromise<TokenResult>;
+}
+export type AuthorizationDefinition<Resume extends JsonValue = JsonValue> = NonInteractiveAuthorizationDefinition | OAuthAuthorizationDefinition | InteractiveAuthorizationDefinition<Resume>;
+export type ConnectionAuthProvider = (Omit<NonInteractiveAuthorizationDefinition, "principalType"> & {
+    principalType?: NonInteractiveAuthorizationDefinition["principalType"];
+}) | AuthorizationDefinition;
+export interface ConnectionResolverContext {
+    session: {
+        userId?: string;
+        channel?: string;
+        conversationId?: string;
+        metadata?: JsonObject;
+    };
+    env: Record<string, string | undefined>;
+}
+export type ConnectionAuthResolver = (ctx: ConnectionResolverContext) => MaybePromise<ConnectionAuthProvider>;
+export type ConnectionAuthDefinition = ConnectionAuthProvider | ConnectionAuthResolver;
+/**
+ * Redeems a user-provided one-time pairing code (a binding packet, setup
+ * code, or claim token pasted into chat) for the connection's credentials.
+ * Runs HOST-side: the returned TokenResult is stored in the grant store, so
+ * the durable credential never lives in a sandbox and the model only ever
+ * relays a single-use code. Providers that rotate refresh tokens should
+ * return them here; refresh then follows the connection's normal auth flow.
+ */
+export type ConnectionPairingRedeemer = (input: {
+    code: string;
+}, ctx: ConnectionResolverContext) => MaybePromise<TokenResult>;
+export type HeaderValue = string | Promise<string> | ((ctx: ConnectionResolverContext) => MaybePromise<string>);
+export type HeadersDefinition = Record<string, HeaderValue> | ((ctx: ConnectionResolverContext) => MaybePromise<Record<string, string>>);
+export type ToolFilterDefinition = {
+    allow: string[];
+} | {
+    block: string[];
+};
+/**
+ * Explicit tool-level authority for a live connection. Patterns are matched
+ * against remote tool/operation names. Write matches take precedence so a
+ * broad read pattern can never bypass a write approval gate.
+ */
+export interface ConnectionAccessDefinition {
+    read: {
+        tools: string[];
+    };
+    write: false | {
+        tools: string[];
+        approval: ConnectionApprovalDefinition;
+    };
+}
+export interface ConnectionApprovalPolicy {
+    mode: "never" | "always" | "once";
+    reason?: string;
+}
+export type ConnectionApprovalDefinition = ApprovalPolicy | ConnectionApprovalPolicy | boolean;
+/**
+ * A credential file projected into the agent sandbox at boot. `path` and
+ * `content` are templates: `{{token}}` renders to the connection's resolved
+ * access token (refreshed host-side through the normal grant flow — the
+ * refresh token itself never enters the sandbox). Files land with `mode`
+ * (default 0600). Put paths outside /workspace, or under /workspace/.openeve/,
+ * so workspace artifact scans never sweep them into durable storage.
+ */
+export interface ConnectionMaterializeFile {
+    path: string;
+    content: string;
+    mode?: number;
+}
+/**
+ * Declares that a connection's credential should be materialized into the
+ * agent sandbox — for CLIs and processes that run inside the sandbox and
+ * cannot route through the host-side connection clients. Only the short-lived
+ * access token is ever rendered; rotation and grant storage stay host-side.
+ */
+export interface ConnectionMaterializeDefinition {
+    files: ConnectionMaterializeFile[];
+}
+interface McpConnectionDefinitionBase {
+    description: string;
+    tools?: ToolFilterDefinition;
+    access: ConnectionAccessDefinition;
+    approval?: ConnectionApprovalDefinition;
+    required?: boolean;
+    subject?: ConnectionDefinition["subject"];
+    metadata?: JsonObject;
+}
+/** An MCP server reached through Streamable HTTP. `transport` is optional for backwards compatibility. */
+export interface McpHttpClientConnectionDefinition extends McpConnectionDefinitionBase {
+    transport?: "http";
+    url: string;
+    auth?: ConnectionAuthDefinition;
+    headers?: HeadersDefinition;
+    materialize?: ConnectionMaterializeDefinition;
+    redeemPairingCode?: ConnectionPairingRedeemer;
+}
+/**
+ * A static, same-host MCP server launched directly by the OpenEve Node host.
+ * The runtime never evaluates these values through a shell.
+ */
+export interface McpStdioClientConnectionDefinition extends McpConnectionDefinitionBase {
+    transport: "stdio";
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    url?: never;
+    auth?: never;
+    headers?: never;
+    materialize?: never;
+    redeemPairingCode?: never;
+}
+/**
+ * An end-to-end encrypted MCP-compatible device connection routed through an
+ * OpenEve computer relay. The binding credential is resolved only by the
+ * runtime host and contains the device-scoped authentication and E2EE keys.
+ */
+export interface McpRelayClientConnectionDefinition extends McpConnectionDefinitionBase {
+    transport: "relay";
+    url: string;
+    credentialEnv: string;
+    timeoutMs?: number;
+    auth?: never;
+    headers?: never;
+    materialize?: never;
+    redeemPairingCode?: never;
+}
+export type McpClientConnectionDefinition = McpHttpClientConnectionDefinition | McpStdioClientConnectionDefinition | McpRelayClientConnectionDefinition;
+export type OpenAPISpecSource = string | JsonObject;
+export interface OpenAPIConnectionDefinition {
+    spec: OpenAPISpecSource;
+    baseUrl?: string;
+    description: string;
+    auth?: ConnectionAuthDefinition;
+    headers?: HeadersDefinition;
+    operations?: ToolFilterDefinition;
+    access: ConnectionAccessDefinition;
+    approval?: ConnectionApprovalDefinition;
+    materialize?: ConnectionMaterializeDefinition;
+    redeemPairingCode?: ConnectionPairingRedeemer;
+    required?: boolean;
+    subject?: ConnectionDefinition["subject"];
+    metadata?: JsonObject;
+}
+export type HttpApiParameterLocation = "path" | "query" | "header" | "cookie";
+export interface HttpApiOperationDefinition {
+    name: string;
+    description: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | Lowercase<"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS">;
+    path: string;
+    inputSchema?: JsonSchema;
+    outputSchema?: JsonSchema;
+    parameters?: Array<{
+        name: string;
+        in: HttpApiParameterLocation;
+        required?: boolean;
+        schema?: JsonSchema;
+    }>;
+    body?: {
+        contentType?: string;
+        field?: string;
+        schema?: JsonSchema;
+    } | boolean;
+}
+export interface HttpApiConnectionDefinition {
+    baseUrl: string;
+    description: string;
+    auth?: ConnectionAuthDefinition;
+    headers?: HeadersDefinition;
+    operations: HttpApiOperationDefinition[];
+    operationFilter?: ToolFilterDefinition;
+    access: ConnectionAccessDefinition;
+    approval?: ConnectionApprovalDefinition;
+    materialize?: ConnectionMaterializeDefinition;
+    redeemPairingCode?: ConnectionPairingRedeemer;
+    required?: boolean;
+    subject?: ConnectionDefinition["subject"];
+    metadata?: JsonObject;
+}
+/**
+ * One reviewed CLI invocation built by a sandbox CLI connection tool.
+ * `args` are passed as individual shell-quoted arguments; model-authored shell
+ * source is never accepted. Logical attachment paths can be hydrated before
+ * the process starts.
+ */
+export interface SandboxCliInvocation {
+    args: string[];
+    cwd?: string;
+    timeoutMs?: number;
+    hydratePaths?: string[];
+}
+export interface SandboxCliToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+    build(input: unknown): MaybePromise<SandboxCliInvocation>;
+}
+/**
+ * A connection whose reviewed tools invoke one external provider CLI inside
+ * the run sandbox. This preserves connection selection, discovery, scoping,
+ * and approval semantics while giving the process access to /files and
+ * /workspace.
+ */
+export interface SandboxCliConnectionDefinition {
+    transport: "sandbox";
+    command: string;
+    description: string;
+    tools: SandboxCliToolDefinition[];
+    access: ConnectionAccessDefinition;
+    approval?: ConnectionApprovalDefinition;
+    auth?: ConnectionAuthDefinition;
+    headers?: never;
+    materialize?: ConnectionMaterializeDefinition;
+    redeemPairingCode?: ConnectionPairingRedeemer;
+    maxOutputChars?: number;
+    required?: boolean;
+    subject?: ConnectionDefinition["subject"];
+    metadata?: JsonObject;
+}
+export {};
+//# sourceMappingURL=connection-types.d.ts.map

package/dist/connection-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-types.d.ts","sourceRoot":"","sources":["../src/connection-types.ts"],"names":[],"mappings":"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"}

package/dist/connection-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=connection-types.js.map

package/dist/connection-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-types.js","sourceRoot":"","sources":["../src/connection-types.ts"],"names":[],"mappings":""}

package/dist/definitions.d.ts

@@ -0,0 +1,98 @@
+import type { AgentDefinition, AutomationDefinition, AutomationHandlerDefinition, ApprovalPolicy, ChannelDefinition, ConnectionDefinition, ContextPolicy, GatewayDefinition, HttpApiConnectionDefinition, InstrumentationDefinition, InteractiveAuthorizationDefinition, JsonObject, JsonValue, MaybePromise, McpHttpClientConnectionDefinition, McpRelayClientConnectionDefinition, McpStdioClientConnectionDefinition, OAuthAuthorizationDefinition, OpenAPIConnectionDefinition, SandboxCliConnectionDefinition, SandboxDefinition, ScheduleDefinition, SubagentDefinition, ToolDefinition, TriggerHandlerDefinition } from "./index.js";
+export declare function defineAgent(definition: AgentDefinition): AgentDefinition;
+export declare function defineSubagent(definition: SubagentDefinition): SubagentDefinition;
+export declare function defineGateway(definition: GatewayDefinition): GatewayDefinition;
+export declare function defaultContext(options?: JsonObject): ContextPolicy;
+export declare function defineContext(policy: ContextPolicy): ContextPolicy;
+export declare function defineTool<Input = unknown, Output = unknown, ModelOutput = unknown>(definition: ToolDefinition<Input, Output, ModelOutput>): ToolDefinition<Input, Output, ModelOutput>;
+/**
+ * The built-in harness tool slugs. An authored file at `tools/<name>.ts` with one
+ * of these names overrides the built-in; a `disableTool()` export removes it.
+ */
+export declare const BUILT_IN_HARNESS_TOOL_NAMES: readonly ["read", "write", "edit", "delete", "list", "grep", "bash", "ask_question", "spawn_subagent", "load_skill", "tool_search", "tool_describe", "tool_call"];
+export declare function isBuiltInHarnessToolName(name: string): boolean;
+export interface DisabledToolSentinel {
+    openeveDisabledTool: true;
+}
+/**
+ * Default-export from `tools/<name>.ts` to remove the built-in tool of that name.
+ * The filename selects the tool; a name that matches no built-in fails the build.
+ */
+export declare function disableTool(): DisabledToolSentinel;
+export declare function isDisabledToolSentinel(value: unknown): value is DisabledToolSentinel;
+/** A durable run event as delivered to hooks, after it is persisted. */
+export interface HookRunEvent {
+    type: string;
+    timestamp: string;
+    data: JsonObject;
+    sequence?: number;
+}
+export interface HookEventContext {
+    runId: string;
+    agent: {
+        name: string;
+    };
+}
+export type HookEventHandler = (event: HookRunEvent, ctx: HookEventContext) => MaybePromise<void>;
+/**
+ * An observe-only subscriber authored at `hooks/<name>.ts`. Handlers are keyed
+ * by event type (`*` matches every event), fire after the event is durably
+ * recorded, and can never alter or fail the run — thrown errors are logged
+ * and swallowed.
+ */
+export interface HookDefinition {
+    events: Record<string, HookEventHandler>;
+}
+export declare function defineHook(definition: HookDefinition): HookDefinition;
+/** The declaration a run resolver returns; the runtime records and applies it. */
+export interface RunResolution {
+    /** Overrides the manifest model for this run (host-forced models still win). */
+    model?: string;
+    /** Appended to the authored instructions for this run. */
+    instructions?: string;
+    /**
+     * Replaces the default-visible tool set for this run (built-in names
+     * included — list every tool the model should start with).
+     */
+    defaultTools?: string[];
+}
+export interface RunResolverContext {
+    runId: string;
+    agent: {
+        name: string;
+    };
+    message: string;
+    channel?: string;
+    conversationId?: string;
+    metadata?: JsonObject;
+    env: Record<string, string | undefined>;
+}
+/**
+ * Authored at `resolvers.ts`: decides per-run model, instructions, and default
+ * tool set from the run context. Runs once per run; the returned declaration
+ * is recorded as a `run.capabilities_resolved` event before it is applied.
+ */
+export type RunResolverDefinition = (ctx: RunResolverContext) => MaybePromise<RunResolution | null | undefined>;
+export declare function defineRunResolver(definition: RunResolverDefinition): RunResolverDefinition;
+export declare function defineChannel(definition: ChannelDefinition): ChannelDefinition;
+/** @deprecated Use `defineAutomation` with `trigger.type = "schedule"`. */
+export declare function defineSchedule(definition: ScheduleDefinition): ScheduleDefinition;
+export declare function defineAutomation(definition: AutomationDefinition): AutomationDefinition;
+export declare function defineAutomationHandler(definition: AutomationHandlerDefinition): AutomationHandlerDefinition;
+/** @deprecated Use `defineAutomationHandler`. */
+export declare function defineTriggerHandler(definition: TriggerHandlerDefinition): TriggerHandlerDefinition;
+export declare function defineConnection(definition: ConnectionDefinition): ConnectionDefinition;
+export declare function defineMcpClientConnection(definition: McpHttpClientConnectionDefinition): McpHttpClientConnectionDefinition;
+export declare function defineMcpStdioConnection(definition: McpStdioClientConnectionDefinition): McpStdioClientConnectionDefinition;
+export declare function defineMcpRelayConnection(definition: McpRelayClientConnectionDefinition): McpRelayClientConnectionDefinition;
+export declare function defineOpenAPIConnection(definition: OpenAPIConnectionDefinition): OpenAPIConnectionDefinition;
+export declare function defineHttpApiConnection(definition: HttpApiConnectionDefinition): HttpApiConnectionDefinition;
+export declare function defineSandboxCliConnection(definition: SandboxCliConnectionDefinition): SandboxCliConnectionDefinition;
+export declare function defineOAuthAuthorization(definition: Omit<OAuthAuthorizationDefinition, "principalType">): OAuthAuthorizationDefinition;
+export declare function defineInteractiveAuthorization<Resume extends JsonValue = never>(definition: Omit<InteractiveAuthorizationDefinition<Resume>, "principalType">): InteractiveAuthorizationDefinition<Resume>;
+export declare function defineSandbox(definition: SandboxDefinition): SandboxDefinition;
+export declare function defineInstrumentation(definition: InstrumentationDefinition): InstrumentationDefinition;
+export declare function approvalRequired(reason: string, sideEffect?: ApprovalPolicy["sideEffect"]): ApprovalPolicy;
+export declare function approvalNever(): ApprovalPolicy;
+export declare function normalizeApprovalPolicy(policy: boolean | ApprovalPolicy | undefined): ApprovalPolicy;
+//# sourceMappingURL=definitions.d.ts.map

package/dist/definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../src/definitions.ts"],"names":[],"mappings":"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"}

package/dist/definitions.js

@@ -0,0 +1,193 @@
+import { validateConnectionAccess, validateConnectionAuthDefinition, validateToolFilter } from "./connection-auth.js";
+export function defineAgent(definition) {
+    return definition;
+}
+export function defineSubagent(definition) {
+    return definition;
+}
+export function defineGateway(definition) {
+    return definition;
+}
+export function defaultContext(options = {}) {
+    return { kind: "default", name: "defaultContext", options };
+}
+export function defineContext(policy) {
+    return policy;
+}
+export function defineTool(definition) {
+    return definition;
+}
+/**
+ * The built-in harness tool slugs. An authored file at `tools/<name>.ts` with one
+ * of these names overrides the built-in; a `disableTool()` export removes it.
+ */
+export const BUILT_IN_HARNESS_TOOL_NAMES = [
+    "read",
+    "write",
+    "edit",
+    "delete",
+    "list",
+    "grep",
+    "bash",
+    "ask_question",
+    "spawn_subagent",
+    "load_skill",
+    "tool_search",
+    "tool_describe",
+    "tool_call"
+];
+const BUILT_IN_HARNESS_TOOL_NAME_SET = new Set(BUILT_IN_HARNESS_TOOL_NAMES);
+export function isBuiltInHarnessToolName(name) {
+    return BUILT_IN_HARNESS_TOOL_NAME_SET.has(name);
+}
+/**
+ * Default-export from `tools/<name>.ts` to remove the built-in tool of that name.
+ * The filename selects the tool; a name that matches no built-in fails the build.
+ */
+export function disableTool() {
+    return { openeveDisabledTool: true };
+}
+export function isDisabledToolSentinel(value) {
+    return Boolean(value) && typeof value === "object" && value.openeveDisabledTool === true;
+}
+export function defineHook(definition) {
+    return definition;
+}
+export function defineRunResolver(definition) {
+    return definition;
+}
+export function defineChannel(definition) {
+    return definition;
+}
+/** @deprecated Use `defineAutomation` with `trigger.type = "schedule"`. */
+export function defineSchedule(definition) {
+    return definition;
+}
+export function defineAutomation(definition) {
+    return definition;
+}
+export function defineAutomationHandler(definition) {
+    return definition;
+}
+/** @deprecated Use `defineAutomationHandler`. */
+export function defineTriggerHandler(definition) {
+    return definition;
+}
+export function defineConnection(definition) {
+    return definition;
+}
+export function defineMcpClientConnection(definition) {
+    validateConnectionAuthDefinition(definition.auth, "defineMcpClientConnection");
+    validateToolFilter(definition.tools, "defineMcpClientConnection");
+    validateConnectionAccess(definition.access, "defineMcpClientConnection");
+    if (definition.transport !== undefined && definition.transport !== "http") {
+        throw new Error("defineMcpClientConnection: transport must be http when provided.");
+    }
+    if (!definition.url.trim())
+        throw new Error("defineMcpClientConnection: url is required.");
+    return definition;
+}
+export function defineMcpStdioConnection(definition) {
+    validateToolFilter(definition.tools, "defineMcpStdioConnection");
+    validateConnectionAccess(definition.access, "defineMcpStdioConnection");
+    if (definition.transport !== "stdio")
+        throw new Error("defineMcpStdioConnection: transport must be stdio.");
+    if (!definition.command.trim())
+        throw new Error("defineMcpStdioConnection: command is required.");
+    if (definition.args?.some((argument) => typeof argument !== "string")) {
+        throw new Error("defineMcpStdioConnection: args must contain only strings.");
+    }
+    if (definition.env && Object.values(definition.env).some((value) => typeof value !== "string")) {
+        throw new Error("defineMcpStdioConnection: env overrides must contain only strings.");
+    }
+    return definition;
+}
+export function defineMcpRelayConnection(definition) {
+    validateToolFilter(definition.tools, "defineMcpRelayConnection");
+    validateConnectionAccess(definition.access, "defineMcpRelayConnection");
+    if (definition.transport !== "relay")
+        throw new Error("defineMcpRelayConnection: transport must be relay.");
+    if (!definition.url.trim())
+        throw new Error("defineMcpRelayConnection: url is required.");
+    const url = new URL(definition.url);
+    const localDevelopment = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+    if (url.protocol !== "https:" && !(localDevelopment && url.protocol === "http:")) {
+        throw new Error("defineMcpRelayConnection: url must use HTTPS (HTTP is allowed only for localhost development).");
+    }
+    if (!/^[A-Z_][A-Z0-9_]*$/u.test(definition.credentialEnv)) {
+        throw new Error("defineMcpRelayConnection: credentialEnv must be an uppercase environment variable name.");
+    }
+    if (definition.timeoutMs !== undefined && (!Number.isInteger(definition.timeoutMs) || definition.timeoutMs < 1_000 || definition.timeoutMs > 120_000)) {
+        throw new Error("defineMcpRelayConnection: timeoutMs must be an integer between 1000 and 120000.");
+    }
+    return definition;
+}
+export function defineOpenAPIConnection(definition) {
+    validateConnectionAuthDefinition(definition.auth, "defineOpenAPIConnection");
+    validateToolFilter(definition.operations, "defineOpenAPIConnection");
+    validateConnectionAccess(definition.access, "defineOpenAPIConnection");
+    return definition;
+}
+export function defineHttpApiConnection(definition) {
+    validateConnectionAuthDefinition(definition.auth, "defineHttpApiConnection");
+    validateToolFilter(definition.operationFilter, "defineHttpApiConnection");
+    validateConnectionAccess(definition.access, "defineHttpApiConnection");
+    if (!definition.operations.length) {
+        throw new Error("defineHttpApiConnection: at least one operation is required.");
+    }
+    return definition;
+}
+export function defineSandboxCliConnection(definition) {
+    validateConnectionAuthDefinition(definition.auth, "defineSandboxCliConnection");
+    validateConnectionAccess(definition.access, "defineSandboxCliConnection");
+    if (definition.transport !== "sandbox") {
+        throw new Error("defineSandboxCliConnection: transport must be sandbox.");
+    }
+    if (!definition.command.trim() || /[\0\r\n]/u.test(definition.command)) {
+        throw new Error("defineSandboxCliConnection: command must be one executable name or path.");
+    }
+    if (!definition.tools.length) {
+        throw new Error("defineSandboxCliConnection: at least one tool is required.");
+    }
+    const names = new Set();
+    for (const tool of definition.tools) {
+        if (!tool.name.trim() || names.has(tool.name)) {
+            throw new Error(`defineSandboxCliConnection: tool names must be non-empty and unique (${tool.name}).`);
+        }
+        if (!tool.description.trim() || typeof tool.build !== "function") {
+            throw new Error(`defineSandboxCliConnection: tool ${tool.name} must declare description and build.`);
+        }
+        names.add(tool.name);
+    }
+    if (definition.maxOutputChars !== undefined
+        && (!Number.isInteger(definition.maxOutputChars) || definition.maxOutputChars < 1_000)) {
+        throw new Error("defineSandboxCliConnection: maxOutputChars must be an integer of at least 1000.");
+    }
+    return definition;
+}
+export function defineOAuthAuthorization(definition) {
+    return { ...definition, principalType: "user" };
+}
+export function defineInteractiveAuthorization(definition) {
+    return { ...definition, principalType: "user" };
+}
+export function defineSandbox(definition) {
+    return definition;
+}
+export function defineInstrumentation(definition) {
+    return definition;
+}
+export function approvalRequired(reason, sideEffect = "external") {
+    return { mode: "always", reason, sideEffect };
+}
+export function approvalNever() {
+    return { mode: "never", sideEffect: "none" };
+}
+export function normalizeApprovalPolicy(policy) {
+    if (policy === true)
+        return { mode: "always", sideEffect: "external" };
+    if (policy === false || policy === undefined)
+        return { mode: "never", sideEffect: "none" };
+    return policy;
+}
+//# sourceMappingURL=definitions.js.map

package/dist/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../src/definitions.ts"],"names":[],"mappings":"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"}