/** The four canonical app-tool names. Stable identifiers the model calls in
 *  both the sandbox (MCP server name) and runtime (function-tool name) paths. */
declare const APP_TOOL_NAMES: readonly ["submit_proposal", "schedule_followup", "render_ui", "add_citation"];
type AppToolName = (typeof APP_TOOL_NAMES)[number];
declare function isAppToolName(name: string): name is AppToolName;
/** A minimal OpenAI Chat Completions function-tool shape — structurally
 *  compatible with `@tangle-network/agent-runtime`'s `OpenAIChatTool` without
 *  importing it (keeps this package runtime-free). */
interface OpenAIFunctionTool {
    type: 'function';
    function: {
        name: string;
        description: string;
        parameters: Record<string, unknown>;
    };
}
/**
 * Build the four app tools in OpenAI function-tool shape. `submit_proposal`'s
 * `type` enum is the product's {@link AppToolTaxonomy.proposalTypes}; the
 * model-facing descriptions and the follow-up priority enum default to the
 * Tangle reference vocabulary and can be retuned via {@link BuildAppToolsOptions}
 * (the tool names + JSON-Schema shapes stay fixed — they are mechanism). Pass
 * the result to the agent-runtime backend's `tools`.
 */
declare function buildAppToolOpenAITools(taxonomy: AppToolTaxonomy, opts?: BuildAppToolsOptions): OpenAIFunctionTool[];

/**
 * A product-defined app tool — the open registration seam.
 *
 * The four built-ins (`submit_proposal`/`schedule_followup`/`render_ui`/
 * `add_citation`) are mechanism and stay hard-typed. This is how a product adds
 * a fifth+ tool (e.g. gtm-agent's `set_config`) WITHOUT forking the shell: the
 * `name` + JSON-Schema `parameters` are what the model sees, and `execute` is
 * dispatched through the SAME validation/outcome path as the built-ins — a
 * thrown {@link ToolInputError} becomes a correctable 4xx, any other throw an
 * internal error, and a tool call never silently "succeeds" without its effect.
 */
interface AppToolDefinition<Args = Record<string, unknown>> {
    /** Stable identifier the model calls (and the MCP server name). Must not
     *  collide with a built-in app tool. */
    name: string;
    /** Model-facing description. */
    description: string;
    /** JSON-Schema for the parameters (the OpenAI `function.parameters` object). */
    parameters: Record<string, unknown>;
    /** Default route path the per-turn MCP server / HTTP handler is mounted at.
     *  Overridable per call via `paths`/`buildHttpMcpServer`. */
    path?: string;
    /** Fulfil the call; the return value is the tool result the model sees.
     *  `ctx` is the trusted per-turn identity (never from tool args). */
    execute: (args: Args, ctx: AppToolContext) => Promise<unknown> | unknown;
}
/**
 * Validate + brand a product tool definition. Throws when the name is empty or
 * collides with a built-in (those are reserved mechanism). Identity otherwise —
 * call it at module scope so a bad definition fails at boot, not first use.
 */
declare function defineAppTool<Args = Record<string, unknown>>(def: AppToolDefinition<Args>): AppToolDefinition<Args>;
/** The OpenAI function-tool def for a custom tool — appended to the built-ins by
 *  `buildAppToolOpenAITools`. */
declare function customToolToOpenAI(def: AppToolDefinition): OpenAIFunctionTool;
/** Find a registered custom tool by the name the model called. */
declare function findCustomTool(name: string, tools: readonly AppToolDefinition[] | undefined): AppToolDefinition | undefined;

/**
 * The structured agent→app tool side channel, domain-seamed.
 *
 * Every Tangle agent product needs the same thing: a way for the in-sandbox
 * agent to reach the host app with a STRUCTURED, validated tool call (not a
 * fenced `:::` block scraped from prose). Four canonical tools cover it:
 *
 *   - `submit_proposal`   — route a regulated/state-changing action to a human
 *                           approval queue (the human-in-the-loop gate).
 *   - `schedule_followup` — register a dated cadence step (executes immediately).
 *   - `render_ui`         — persist a generated view as an artifact (immediate).
 *   - `add_citation`      — anchor a grounding reference (immediate).
 *
 * The shapes, validation, OpenAI tool definitions, MCP-server wiring, HTTP
 * route handling, and runtime-loop executor are GENERIC and live here. The
 * persistence (which DB, which tables) and the product's proposal taxonomy are
 * the DOMAIN SEAM: each product supplies {@link AppToolHandlers} +
 * {@link AppToolTaxonomy}. This package imports no product code and no agent
 * runtime — it depends only on the Web `Request`/`Response` types.
 */
/** Server-set, trusted per-turn context. Recovered from request headers (HTTP
 *  path) or supplied directly (runtime path) — never from model tool args, so
 *  the model cannot forge identity or target another workspace. */
interface AppToolContext {
    userId: string;
    workspaceId: string;
    threadId: string | null;
}
/** The product's proposal taxonomy — the only domain-specific vocabulary the
 *  generic layer needs (to validate `submit_proposal.type` and label the
 *  regulated subset). */
interface AppToolTaxonomy {
    /** Every accepted proposal type. */
    proposalTypes: readonly string[];
    /** The subset that cannot execute without a named certified human (regulated
     *  steps). Used only to label the tool result; enforcement is the product's
     *  approval executor. */
    regulatedTypes: readonly string[];
}
/** Optional overrides for {@link buildAppToolOpenAITools}. The tool NAMES and
 *  JSON-Schema parameter shapes are mechanism (stable identifiers the model and
 *  both transports rely on); the model-facing PROSE and the follow-up priority
 *  vocabulary are domain — a product with no vault/contacts/OpenUI can retune
 *  them here instead of forking the shell. Omit for the defaults. */
interface BuildAppToolsOptions {
    /** Override the model-facing description of any of the four tools. */
    descriptions?: Partial<Record<'submit_proposal' | 'schedule_followup' | 'render_ui' | 'add_citation', string>>;
    /** The `schedule_followup.priority` enum (defaults to `['low','medium','high']`). */
    priorityValues?: readonly string[];
    /** Product-registered tools to advertise to the model alongside the four
     *  built-ins (appended in order, after the built-ins). */
    customTools?: readonly AppToolDefinition[];
}
interface SubmitProposalArgs {
    type: string;
    title: string;
    description?: string | null;
    /** Stamped by dispatch from the approval policy (needsApproval predicate or
     *  taxonomy.regulatedTypes). Handlers MUST queue (never auto-execute) when
     *  true. Products don't set this; dispatch owns it — fail-closed. */
    regulated?: boolean;
}
interface SubmitProposalResult {
    proposalId: string;
    /** True when an identical (workspace, title) proposal already existed. */
    deduped: boolean;
    /** Handlers that execute a proposal type immediately (an unregulated
     *  generate-style action) return 'executed'; omitted/'queued_for_approval'
     *  means a human gate. Dispatch reports this verbatim to the model. */
    status?: 'queued_for_approval' | 'executed';
    /** Product-specific result fields (e.g. datasetId) — passed through to the
     *  tool outcome so the model and UI see what the handler actually did. */
    [extra: string]: unknown;
}
interface ScheduleFollowupArgs {
    title: string;
    dueDate: string;
    priority?: string;
}
interface ScheduleFollowupResult {
    id: string;
    dueDate: string;
    deduped: boolean;
}
interface RenderUiArgs {
    title: string;
    schema: unknown;
}
interface RenderUiResult {
    /** The persisted artifact path. */
    path: string;
    /** The exact persisted body — surfaced as the `artifact` produced event so a
     *  consumer's completion oracle sees the real content. */
    content: string;
}
interface AddCitationArgs {
    path: string;
    quote: string;
    label?: string;
}
interface AddCitationResult {
    citationId: string;
    path: string;
}
/**
 * The domain seam. Each product implements these against its own D1/KV/vault.
 * A handler MAY throw {@link ToolInputError} for correctable bad input (mapped
 * to a 4xx / failed tool_result); any other throw is an internal error.
 * `submitProposal` is the only handler whose result feeds the approval queue;
 * the others execute immediately.
 */
interface AppToolHandlers {
    submitProposal(args: SubmitProposalArgs, ctx: AppToolContext): Promise<SubmitProposalResult>;
    scheduleFollowup(args: ScheduleFollowupArgs, ctx: AppToolContext): Promise<ScheduleFollowupResult>;
    renderUi(args: RenderUiArgs, ctx: AppToolContext): Promise<RenderUiResult>;
    addCitation(args: AddCitationArgs, ctx: AppToolContext): Promise<AddCitationResult>;
}
/** Produced-state events the runtime executor emits at the real side-effect
 *  site, so a consumer's eval/completion oracle credits a persisted proposal or
 *  artifact. Deliberately substrate-free (no RuntimeStreamEvent import); the
 *  consumer maps these onto its own telemetry shape. */
type AppToolProducedEvent = {
    type: 'proposal_created';
    proposalId: string;
    title: string;
    status: 'pending' | 'executed';
    content?: string;
} | {
    type: 'artifact';
    path: string;
    content: string;
};
/** Outcome of one tool dispatch — structurally identical to the agent-runtime
 *  tool-loop's `ToolCallOutcome`, so a dispatched outcome folds straight into
 *  the loop's `role: 'tool'` result message. Defined here (not imported) to keep
 *  the `tools/` module substrate-free: it depends only on Web `Request`/
 *  `Response`, never on the agent runtime. */
type AppToolOutcome = {
    ok: true;
    result: unknown;
} | {
    ok: false;
    code: string;
    message: string;
    status?: number;
};

export { APP_TOOL_NAMES as A, type BuildAppToolsOptions as B, type OpenAIFunctionTool as O, type RenderUiArgs as R, type ScheduleFollowupArgs as S, type AddCitationArgs as a, type AddCitationResult as b, type AppToolContext as c, type AppToolDefinition as d, type AppToolHandlers as e, type AppToolName as f, type AppToolOutcome as g, type AppToolProducedEvent as h, type AppToolTaxonomy as i, type RenderUiResult as j, type ScheduleFollowupResult as k, type SubmitProposalArgs as l, type SubmitProposalResult as m, buildAppToolOpenAITools as n, customToolToOpenAI as o, defineAppTool as p, findCustomTool as q, isAppToolName as r };
