@retinue/agentkit 0.1.0

package/dist/tools/delegating.d.ts

@@ -0,0 +1,132 @@
+import type { ExecutionContext } from "../core/context.js";
+import type { AuthorizationPolicy } from "../authorization/index.js";
+import { type IdempotencyKey, type IdempotencyStore } from "../idempotency/index.js";
+import type { ApprovalGate } from "../hitl/service.js";
+import { type ToolSpec } from "./define.js";
+import { type SchemaValidator, type ToolMisconfiguration } from "./registry.js";
+import type { ShadowRecorder, Tool } from "./index.js";
+export type DelegatingToolSpec<I = unknown, O = unknown> = Omit<ToolSpec<I, O>, "execute"> & {
+    /**
+     * The function this capability wraps, named so a reviewer can see it (AC-6).
+     *
+     * **Required**, not optional. A comment does not survive review at scale, and "which existing
+     * function does this delegate to" is the question the whole bridge exists to make answerable — so a
+     * capability that does not say what it wraps cannot be defined.
+     */
+    readonly delegatesTo: string;
+    /**
+     * The deterministic function. Receives validated input, the execution context and the call's
+     * idempotency key; returns data or throws. Knows nothing about authorisation or approvals.
+     */
+    delegate(input: I, context: ExecutionContext, details: DelegateDetails): Promise<O> | O;
+    /**
+     * A check that runs **before the approval gate** (#119 AC-4).
+     *
+     * The general property, not a publishing one: *do not ask a person to authorise something that
+     * cannot succeed*. Content validation placed inside the delegate runs after the gate, so a human
+     * would already have approved something that then fails — which teaches them their approval does not
+     * mean much.
+     *
+     * Throw to refuse. The thrown error is returned as-is, so a preflight that has structured findings
+     * can carry them in `details` rather than flattening them into a sentence.
+     *
+     * It must be **read-only**. It runs on every call including one that is about to be refused for want
+     * of an approval, so a preflight with a side effect would be a side effect that happens without
+     * approval — the exact thing the gate exists to prevent.
+     */
+    preflight?(input: I, context: ExecutionContext): Promise<void> | void;
+};
+/**
+ * What the envelope tells the delegate about the call itself.
+ *
+ * An object rather than a bare string so that adding a field later is additive — the same reason
+ * `ShareFlowServices` is one object rather than four arguments.
+ */
+export type DelegateDetails = {
+    /**
+     * The key this call was deduplicated under.
+     *
+     * Passed on so a delegate can hand it to a downstream service whose own queue needs it. **Not** for
+     * the delegate to check: the envelope has already looked it up, and a delegate that consulted it
+     * would be doing the lookup twice with the second one unguarded.
+     */
+    readonly idempotencyKey: IdempotencyKey;
+};
+export type DelegatingToolDeps = {
+    readonly authorization: AuthorizationPolicy;
+    /**
+     * Consulted for gated effects. Absent means no capability with an external-write or destructive
+     * effect can run — refusing is the safe default, since the alternative is performing an unapproved
+     * side effect because a dependency was not wired.
+     */
+    readonly approvals?: ApprovalGate;
+    /**
+     * Where "this tool can never run" is reported — #162, the same sink and the same shape the registry uses.
+     *
+     * Deliberately not a separate type: the case that misled in #155 was wiring one layer and not the other, so
+     * a host that reports both through one function sees "registry" and "delegating-envelope" side by side
+     * instead of guessing which file to open.
+     */
+    readonly onMisconfiguration?: (report: ToolMisconfiguration) => void;
+    /**
+     * Where a first result is stored so a retry returns it. Absent means gated effects are refused for
+     * the same reason: an external write with no replay protection is exactly the thing this envelope
+     * exists to prevent. See the open question on #113.
+     */
+    readonly idempotency?: IdempotencyStore;
+    /**
+     * Validates `input` against the spec's `inputSchema` before the delegate is reached (#115 AC-5).
+     *
+     * Defaults to `zodishValidator`, which passes through anything that is not a zod-like schema — and
+     * `inputSchema` itself defaults to `{}` — so a tool that declares no schema behaves exactly as it did
+     * before this existed.
+     *
+     * The registry already re-validates at execution, which covers the production path. This covers
+     * *every* path: a tool executed directly, from a test, or from a future caller that is not the
+     * registry. The envelope's whole purpose is that a guarantee cannot be reached around.
+     */
+    readonly validator?: SchemaValidator;
+    /**
+     * Where a shadow run's suppressed writes go.
+     *
+     * Required *when the run says it is shadow*: `context.shadow === true` with no recorder is refused
+     * rather than performed. Announcing a shadow run and having nowhere to record it is not a licence to
+     * publish — the same fail-closed reasoning as the missing approval gate.
+     */
+    readonly shadow?: ShadowRecorder;
+};
+/**
+ * The key used when the caller supplied none.
+ *
+ * **Weaker protection than the caller's key, and stronger collision behaviour — both worth knowing.**
+ * `ToolExecutionInput.idempotencyKey` is documented as derived from tenant, run and tool-call identity,
+ * which makes a *retry of one call* safe. This fallback is derived from tenant, conversation, tool and
+ * normalised arguments, as the SPEC describes, which collides for *any* call with identical arguments
+ * **across runs**: "publish this post" today and the same call next week produce the same key, so the
+ * second would return the first result and never publish.
+ *
+ * That is suppression of an intended action rather than deduplication of a retry, so the caller's key
+ * is always preferred. This exists only so a tool invoked without one is not left unprotected. See the
+ * open question on #113 about whether the run belongs in it.
+ */
+export declare const fallbackIdempotencyKey: (input: {
+    readonly context: ExecutionContext;
+    readonly toolName: string;
+    readonly args: unknown;
+}) => IdempotencyKey;
+/**
+ * Build a `Tool` whose execute path is: authorise → validate → derive key → look up → preflight → shadow →
+ * approval gate → delegate → store.
+ *
+ * The lookup sits **before** the approval gate deliberately. A call whose result is already stored has
+ * already been approved and executed, so re-gating it would either block a legitimate replay or ask a
+ * human to approve one action twice.
+ *
+ * The descriptor comes from `defineTool` and the error envelope from the same `toPlatformError` a
+ * delegating tool's shape is the existing `ToolResult` **by construction** rather than by resemblance
+ * (AC-5). The execute path is written out here rather than passed to `defineTool`, because the
+ * idempotency key arrives on `ToolExecutionInput` and `defineTool`'s `execute(input, context)` does not
+ * carry it — bridging that with a side table keyed by context worked but read like a trick.
+ */
+export declare const defineDelegatingTool: <I = unknown, O = unknown>(deps: DelegatingToolDeps, spec: DelegatingToolSpec<I, O>) => Tool<O>;
+//# sourceMappingURL=delegating.d.ts.map

package/dist/tools/delegating.js

@@ -0,0 +1,211 @@
+/**
+ * The logic-function tool envelope — `docs/extraction/twenty-sdk-comparison.md` (#113).
+ *
+ * The extraction doc's central decision: *"a tool is a thin, agent-facing envelope over a
+ * deterministic function"* that *"adds the permission filter, the approval gate for external writes
+ * and the idempotency key, then delegates the actual side effect."* Until now that existed only as
+ * prose — there was no `logic-function` reference anywhere in `src`.
+ *
+ * The point of putting it here rather than in each tool is that **a tool cannot forget**. A capability
+ * author writes a `delegate` that does one thing; authorisation, the approval gate and the idempotency
+ * key are applied by construction, in one place, in one order.
+ *
+ * **The delegate is not told whether an approval happened.** It receives validated input, a context and
+ * the call's idempotency key, and returns data — which is what makes a wrapped function still a plain
+ * function, testable on its own.
+ *
+ * The key was originally withheld too, on the reasoning that a delegate should know nothing about any
+ * of this. Writing the first capability that performs a write (#115) showed that to be wrong: the
+ * downstream service needs the key threaded through so a *re-delivered job* is deduplicated, which is
+ * a different guarantee from the one the store here provides. The envelope stops a second agent call;
+ * the downstream key stops a second delivery of one accepted call. Either alone leaves a way to post
+ * twice, and a delegate that cannot pass the key on cannot close that gap. It is still a plain
+ * argument — the delegate remains a function of its inputs.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { assertToolAuthorized } from "../authorization/index.js";
+import { canonicalizeArgs } from "../idempotency/index.js";
+import { toPlatformError } from "../runtime/retry.js";
+import { defineTool } from "./define.js";
+import { zodishValidator } from "./registry.js";
+/** Effects that require an approval decision before the side effect happens. */
+const GATED_EFFECTS = new Set(["external-write", "destructive"]);
+/**
+ * The key used when the caller supplied none.
+ *
+ * **Weaker protection than the caller's key, and stronger collision behaviour — both worth knowing.**
+ * `ToolExecutionInput.idempotencyKey` is documented as derived from tenant, run and tool-call identity,
+ * which makes a *retry of one call* safe. This fallback is derived from tenant, conversation, tool and
+ * normalised arguments, as the SPEC describes, which collides for *any* call with identical arguments
+ * **across runs**: "publish this post" today and the same call next week produce the same key, so the
+ * second would return the first result and never publish.
+ *
+ * That is suppression of an intended action rather than deduplication of a retry, so the caller's key
+ * is always preferred. This exists only so a tool invoked without one is not left unprotected. See the
+ * open question on #113 about whether the run belongs in it.
+ */
+export const fallbackIdempotencyKey = (input) => `${input.context.tenantId}:${input.context.conversationId ?? "-"}:${input.toolName}:${canonicalizeArgs(input.args)}`;
+const refuse = (code, message) => new AgentPlatformError({ code, message, retryable: false });
+/**
+ * Build a `Tool` whose execute path is: authorise → validate → derive key → look up → preflight → shadow →
+ * approval gate → delegate → store.
+ *
+ * The lookup sits **before** the approval gate deliberately. A call whose result is already stored has
+ * already been approved and executed, so re-gating it would either block a legitimate replay or ask a
+ * human to approve one action twice.
+ *
+ * The descriptor comes from `defineTool` and the error envelope from the same `toPlatformError` a
+ * delegating tool's shape is the existing `ToolResult` **by construction** rather than by resemblance
+ * (AC-5). The execute path is written out here rather than passed to `defineTool`, because the
+ * idempotency key arrives on `ToolExecutionInput` and `defineTool`'s `execute(input, context)` does not
+ * carry it — bridging that with a side table keyed by context worked but read like a trick.
+ */
+export const defineDelegatingTool = (deps, spec) => {
+    const effect = spec.effect ?? "read";
+    const gated = GATED_EFFECTS.has(effect);
+    // Descriptor defaults — approval policy and idempotency requirement — come from `defineTool`, so a
+    // delegating tool and a plain one classify an effect identically.
+    const defaults = defineTool({
+        ...spec,
+        execute: () => {
+            throw new Error("unreachable: the delegating envelope owns execution");
+        },
+    });
+    const descriptor = { ...defaults.descriptor, delegatesTo: spec.delegatesTo };
+    /**
+     * Once per envelope, not once per call — #162 AC-2.
+     *
+     * An envelope wraps exactly one tool, so "once per tool" is one boolean here, where the registry needs a
+     * set. Reported on first execution rather than at construction because that is when the misconfiguration
+     * first has a consequence, and because a tool that is never called has no wiring bug worth reporting.
+     */
+    let reportedMisconfiguration = false;
+    const reportMisconfiguration = (toolName, approvalPolicy) => {
+        if (deps.onMisconfiguration === undefined || reportedMisconfiguration)
+            return;
+        reportedMisconfiguration = true;
+        deps.onMisconfiguration({
+            kind: "approval-check-missing",
+            layer: "delegating-envelope",
+            toolName,
+            approvalPolicy,
+            configField: "DelegatingToolDeps.approvals",
+        });
+    };
+    return {
+        descriptor,
+        async execute({ context, input, idempotencyKey, approval }) {
+            try {
+                // Re-authorised here even though discovery already filtered the catalog: the governing
+                // principle is that tools are filtered before discovery *and* re-authorised during execution,
+                // because a role can change between the two and a stale catalog must not be a permission.
+                await assertToolAuthorized(deps.authorization, context, {
+                    name: spec.name,
+                    category: descriptor.category,
+                });
+                // Validated *before* the key is derived, not after.
+                //
+                // Because a schema may normalise — an LLM passes "LinkedIn" where the store keeps "linkedin" —
+                // deriving the fallback key from the raw arguments would give one logical call two different
+                // keys, and the second would not see the first's result. Normalising first makes the key a
+                // property of the call rather than of the model's capitalisation.
+                //
+                // After authorisation, so a caller with no permission learns nothing about the schema.
+                const validated = (deps.validator ?? zodishValidator).validate(descriptor.inputSchema, input);
+                if (!validated.ok)
+                    throw new AgentPlatformError({
+                        code: "invalid_input",
+                        message: `Invalid input for ${spec.name}: ${validated.message}`,
+                        retryable: false,
+                    });
+                // The caller's key is preferred — it is derived from tool-call identity, which is what makes a
+                // *retry* safe. The fallback is broader and can suppress an intended repeat; see its docstring.
+                const key = idempotencyKey ??
+                    fallbackIdempotencyKey({ context, toolName: spec.name, args: validated.value });
+                if (deps.idempotency) {
+                    const stored = await deps.idempotency.get({ tenantId: context.tenantId, key });
+                    // A hit means this call already ran. Returning the stored result *is* the guarantee: the
+                    // delegate is not called again, so the side effect does not happen twice.
+                    if (stored)
+                        return { ok: true, data: stored.result };
+                }
+                else if (gated) {
+                    // Refusing rather than proceeding. An external write with no replay protection is precisely
+                    // what this envelope exists to prevent, and an unwired dependency is not a reason to do it.
+                    throw refuse("capability_unavailable", `${spec.name} performs a ${effect} and no idempotency store is configured`);
+                }
+                // Before the gate, and after the idempotency lookup: a call whose result is already stored has
+                // already run, so re-validating it could refuse a legitimate replay on content that has since
+                // changed underneath it.
+                if (spec.preflight)
+                    await spec.preflight(validated.value, context);
+                // Shadow mode, and **before** the approval gate.
+                //
+                // A shadow run must not ask a human to approve something that will not happen; doing so teaches
+                // people that approving is meaningless, which is the one thing an approval gate cannot survive.
+                //
+                // Only gated effects are suppressed — `external-write` and `destructive`. docs/07 says "shadow
+                // execution performs no external *writes*", so an internal write still happens, and that is worth
+                // knowing: a shadow run does create real drafts. See the note on #126.
+                if (gated && context.shadow === true) {
+                    if (!deps.shadow)
+                        throw refuse("capability_unavailable", `${spec.name} is a ${effect} and this run is in shadow mode with no recorder configured`);
+                    await deps.shadow.record(context, {
+                        ...(context.runId === undefined ? {} : { runId: context.runId }),
+                        toolName: spec.name,
+                        delegatesTo: spec.delegatesTo,
+                        effect,
+                        input: validated.value,
+                        idempotencyKey: key,
+                        wouldRequireApproval: descriptor.approvalPolicy !== "never",
+                    });
+                    // Marked truthfully, and this is the least-bad of three bad options. A fake success would teach
+                    // the agent to report a publish that never happened; a hard failure would change the trajectory
+                    // parity measurement is trying to observe; this changes it too, but honestly.
+                    //
+                    // The limitation is inherent and worth stating rather than hiding: shadow mode measures
+                    // everything up to the external write and nothing after it. What an agent does *after*
+                    // publishing cannot be observed without publishing.
+                    //
+                    // Not stored under the idempotency key: a suppressed call must not become the cached answer for
+                    // a later real one.
+                    return { ok: true, data: { suppressed: true, reason: "shadow-mode", wouldHaveCalled: spec.delegatesTo } };
+                }
+                if (gated) {
+                    if (!deps.approvals) {
+                        // Already distinguishable from a real refusal — `capability_unavailable`, not
+                        // `approval_required`. #162 adds only the once-per-tool report, so the two layers behave alike.
+                        reportMisconfiguration(spec.name, descriptor.approvalPolicy);
+                        throw refuse("capability_unavailable", `${spec.name} performs a ${effect} and no approval gate is configured ` +
+                            `(DelegatingToolDeps.approvals), so it can never run. This is a wiring error, not a refusal.`);
+                    }
+                    // The ticket, when the call carries one, is handed to the gate rather than interpreted here:
+                    // this envelope decides *whether* approval applies, `hitl/service.ts` decides whether a
+                    // given approval is real. An envelope that read the ticket itself would be a second place
+                    // that could get "is this approved" wrong.
+                    const allowed = await deps.approvals.isAllowed(context, {
+                        name: spec.name,
+                        category: descriptor.category,
+                        approvalPolicy: descriptor.approvalPolicy,
+                    }, approval);
+                    // The delegate is never reached. It is not told an approval was needed, refused or granted —
+                    // this envelope decides *whether* approval applies; `hitl/service.ts` decides *how*.
+                    if (!allowed) {
+                        throw refuse("approval_required", `${spec.name} requires approval before it can run`);
+                    }
+                }
+                const data = await spec.delegate(validated.value, context, { idempotencyKey: key });
+                // Stored only after the delegate succeeds, so a failed attempt can be retried rather than
+                // having its own failure permanently cached as the answer.
+                if (deps.idempotency) {
+                    await deps.idempotency.put({ tenantId: context.tenantId, key, result: data });
+                }
+                return { ok: true, data };
+            }
+            catch (error) {
+                return { ok: false, error: toPlatformError(error) };
+            }
+        },
+    };
+};
+//# sourceMappingURL=delegating.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Tool registry — `docs/03-intelligence-runtime.md`.
+ *
+ * The runtime builds a permission-filtered compact catalog. Only commonly required
+ * tools are preloaded; other schemas load lazily. Execution rechecks authorization and
+ * validates input even when the tool was discoverable earlier.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { PlatformError } from "../core/errors.js";
+import type { BlobRef } from "../core/ids.js";
+import type { IdempotencyKey } from "../idempotency/index.js";
+/**
+ * Effect classification. This drives the approval policy, so an unknown effect is
+ * never treated as `read` — see `../mcp` for how imported tools are classified.
+ */
+export declare const TOOL_EFFECTS: readonly ["read", "internal-write", "external-write", "destructive"];
+export type ToolEffect = (typeof TOOL_EFFECTS)[number];
+export type ApprovalPolicy = "never" | "policy" | "always";
+export type ToolDescriptor = {
+    readonly name: string;
+    readonly label: string;
+    readonly description: string;
+    readonly category: string;
+    /** JSON Schema. Validated on execution, not merely advertised. */
+    readonly inputSchema: unknown;
+    readonly outputSchema: unknown;
+    readonly effect: ToolEffect;
+    readonly approvalPolicy: ApprovalPolicy;
+    /** External and destructive tools must supply an idempotency key. */
+    readonly requiresIdempotencyKey: boolean;
+    /**
+     * For a delegating tool (#113): the deterministic function this capability wraps.
+     *
+     * On the descriptor rather than only at the definition site, so "which existing function does this
+     * delegate to" is answerable wherever a tool is visible — a catalog dump, a log line, a review.
+     * Optional because a tool need not delegate; required by `defineDelegatingTool` for those that do.
+     */
+    readonly delegatesTo?: string;
+};
+/** What enters the model's context during discovery: no schemas, just enough to choose. */
+export type ToolCatalogEntry = Pick<ToolDescriptor, "name" | "label" | "description" | "category" | "effect">;
+/** Shared success/error envelope — every tool, including imported ones. */
+export type ToolResult<T = unknown> = {
+    readonly ok: true;
+    readonly data: T;
+    /** Set when the payload was compacted or spilled rather than returned inline. */
+    readonly spilledOutputRef?: BlobRef;
+    readonly truncated?: boolean;
+} | {
+    readonly ok: false;
+    readonly error: PlatformError;
+};
+/**
+ * A single approved execution, presented at the moment of the call.
+ *
+ * Structural on purpose — the tools layer must not depend on `hitl` (the approval *check* is a
+ * structural port here for the same reason). The id is opaque to everything in this layer: whoever
+ * implements the check verifies it against the stored interaction, so passing one along is never the
+ * same as granting anything.
+ */
+export type OneTimeApprovalRef = {
+    readonly interactionId: string;
+};
+export type ToolExecutionInput = {
+    readonly context: ExecutionContext;
+    readonly input: unknown;
+    /** Derived from tenant, run and tool-call identity. Replays return the first result. */
+    readonly idempotencyKey?: string;
+    /**
+     * Set when this call is the execution a human already approved.
+     *
+     * Threaded down to the tool rather than consumed by the registry alone, because a delegating tool
+     * runs its own gate — the registry letting the call through while the envelope refuses it one layer
+     * lower is the same stuck loop, just harder to see.
+     */
+    readonly approval?: OneTimeApprovalRef;
+};
+export interface Tool<T = unknown> {
+    readonly descriptor: ToolDescriptor;
+    execute(input: ToolExecutionInput): Promise<ToolResult<T>>;
+}
+/**
+ * What a shadow run records instead of doing.
+ *
+ * A port rather than a store, because what "recording" means differs by deployment: a parity harness wants
+ * it in memory, a migration wants it durable and comparable to the old runtime's output.
+ *
+ * Here rather than in `delegating.ts` because **two layers suppress**: the registry (which covers every
+ * tool) and the delegating envelope (which covers the direct-execute path). One definition, for the reason
+ * #113's duplicate `toPlatformError` had to be collapsed — two would drift, and a recorder the two layers
+ * disagreed about would under-report exactly the writes it exists to catch.
+ */
+export type SuppressedWrite = {
+    readonly runId?: string;
+    readonly toolName: string;
+    /** The function that would have been called. */
+    readonly delegatesTo: string;
+    readonly effect: ToolEffect;
+    /** Validated input — what would have been sent. */
+    readonly input: unknown;
+    readonly idempotencyKey: IdempotencyKey;
+    /**
+     * Whether this action would have required a human's approval.
+     *
+     * Captured because suppression happens *before* the approval gate — a shadow run must not ask someone to
+     * approve something that will not happen, since that teaches them approving is meaningless. Recording it
+     * keeps the fact the parity report wants without asking the question.
+     */
+    readonly wouldRequireApproval: boolean;
+};
+export interface ShadowRecorder {
+    record(context: ExecutionContext, write: SuppressedWrite): Promise<void> | void;
+}
+/**
+ * Applications register providers rather than individual tools, so a provider can
+ * resolve its tool list against tenant configuration.
+ */
+export interface ToolProvider {
+    readonly id: string;
+    listTools(context: ExecutionContext): Promise<readonly Tool[]>;
+}
+/** Built-in meta-tools. Always present, never provider-supplied. */
+export declare const META_TOOLS: readonly ["learn_tools", "execute_tool", "load_skill", "ask_questions", "request_approval", "read_tool_output"];
+export type MetaToolName = (typeof META_TOOLS)[number];
+export * from "./meta-tools.js";
+export * from "./registry.js";
+export * from "./delegating.js";
+export * from "./define.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,33 @@
+/**
+ * Tool registry — `docs/03-intelligence-runtime.md`.
+ *
+ * The runtime builds a permission-filtered compact catalog. Only commonly required
+ * tools are preloaded; other schemas load lazily. Execution rechecks authorization and
+ * validates input even when the tool was discoverable earlier.
+ */
+/**
+ * Effect classification. This drives the approval policy, so an unknown effect is
+ * never treated as `read` — see `../mcp` for how imported tools are classified.
+ */
+export const TOOL_EFFECTS = [
+    "read",
+    "internal-write",
+    "external-write",
+    "destructive",
+];
+// The authorization port lives in `../authorization` (docs/11) — a single canonical definition
+// used for both discovery filtering and execution permission.
+/** Built-in meta-tools. Always present, never provider-supplied. */
+export const META_TOOLS = [
+    "learn_tools",
+    "execute_tool",
+    "load_skill",
+    "ask_questions",
+    "request_approval",
+    "read_tool_output",
+];
+export * from "./meta-tools.js";
+export * from "./registry.js";
+export * from "./delegating.js";
+export * from "./define.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/library/compute.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Time and arithmetic — REQ-039 (#188).
+ *
+ * The two things worth shipping because a model is reliably bad at them: it has no clock, and it does arithmetic
+ * by pattern rather than by calculation. Both delegate to pure functions in `toolkit/compute.ts`.
+ */
+import type { DelegatingToolDeps } from "../delegating.js";
+import type { Tool } from "../index.js";
+export declare const createNowTool: (deps: DelegatingToolDeps, now?: () => Date) => Tool;
+export declare const createCalculateTool: (deps: DelegatingToolDeps) => Tool;
+//# sourceMappingURL=compute.d.ts.map

package/dist/tools/library/compute.js

@@ -0,0 +1,46 @@
+/**
+ * Time and arithmetic — REQ-039 (#188).
+ *
+ * The two things worth shipping because a model is reliably bad at them: it has no clock, and it does arithmetic
+ * by pattern rather than by calculation. Both delegate to pure functions in `toolkit/compute.ts`.
+ */
+import { z } from "zod";
+import { defineDelegatingTool } from "../delegating.js";
+import { calculate, currentTime } from "../../toolkit/compute.js";
+const timeSchema = z
+    .object({
+    timeZone: z.string().min(1).max(64).optional().describe("An IANA zone like 'Europe/Berlin'. Defaults to the caller's."),
+})
+    .strict();
+export const createNowTool = (deps, now) => defineDelegatingTool(deps, {
+    name: "now",
+    label: "Current date and time",
+    description: "The current date and time. Call this before any answer that depends on today — you do not have a clock, " +
+        "and the date you would otherwise assume is the one you were trained on.",
+    category: "general",
+    effect: "read",
+    inputSchema: timeSchema,
+    delegatesTo: "toolkit/compute.currentTime",
+    delegate: (input, context) => 
+    // The context's timezone when the caller named none: "today" is a different day depending on where the
+    // person asking is, and the execution context already knows which.
+    currentTime({ timeZone: input.timeZone ?? context.timezone, now }),
+});
+const calculateSchema = z
+    .object({
+    expression: z.string().min(1).max(500).describe("Arithmetic: + - * / % ^, parentheses, and functions like sqrt, round, min."),
+})
+    .strict();
+export const createCalculateTool = (deps) => defineDelegatingTool(deps, {
+    name: "calculate",
+    label: "Calculate",
+    description: "Evaluate an arithmetic expression exactly. Use this for any arithmetic that matters rather than doing it " +
+        "yourself. Supports + - * / % ^, parentheses, and abs, ceil, floor, round, sqrt, ln, log10, min, max, pow, " +
+        "and the trigonometric functions. Results are double-precision floats.",
+    category: "general",
+    effect: "read",
+    inputSchema: calculateSchema,
+    delegatesTo: "toolkit/compute.calculate",
+    delegate: (input) => calculate(input.expression),
+});
+//# sourceMappingURL=compute.js.map

package/dist/tools/library/data.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Structured data — REQ-039 (#188).
+ *
+ * Envelopes over `toolkit/data.ts`. `parse_csv` and `query_json` are pure and take their input as text, which is
+ * the deliberate shape: a tool that took a *path* or a *URL* would be a file read or a fetch wearing a parser's
+ * name, and the authorisation for those belongs to `read_attachment` and `fetch_url`. So the model reads with one
+ * tool and parses with another, and each one is checked by the thing that should check it.
+ */
+import type { DelegatingToolDeps } from "../delegating.js";
+import type { Tool } from "../index.js";
+import type { SchemaResult, SqlResult } from "../../toolkit/index.js";
+export declare const createParseCsvTool: (deps: DelegatingToolDeps) => Tool;
+export declare const createQueryJsonTool: (deps: DelegatingToolDeps) => Tool;
+export declare const createSqlQueryTool: (deps: DelegatingToolDeps, run: (sql: string) => Promise<SqlResult>) => Tool;
+export declare const createSqlSchemaTool: (deps: DelegatingToolDeps, describe: () => Promise<SchemaResult>) => Tool;
+//# sourceMappingURL=data.d.ts.map