@punktechnologies/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,162 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of such
+entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative
+Works shall not include works that remain separable from, or merely link (or
+bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the purposes
+of this definition, "submitted" means any form of electronic, verbal, or
+written communication sent to the Licensor or its representatives, including
+but not limited to communication on electronic mailing lists, source code
+control systems, and issue tracking systems that are managed by, or on behalf
+of, the Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise designated
+in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed by
+their Contribution(s) alone or by combination of their Contribution(s) with the
+Work to which such Contribution(s) was submitted. If You institute patent
+litigation against any entity (including a cross-claim or counterclaim in a
+lawsuit) alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent
+licenses granted to You under this License for that Work shall terminate as of
+the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any
+part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a
+whole, provided Your use, reproduction, and distribution of the Work otherwise
+complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability to
+use the Work (including but not limited to damages for loss of goodwill, work
+stoppage, computer failure or malfunction, or any and all other commercial
+damages or losses), even if such Contributor has been advised of the
+possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 Punk Technologies, Inc.

package/README.md

@@ -0,0 +1,169 @@
+# Punk SDK
+
+Public TypeScript SDK and integration examples for Punk, the adaptive runtime for production AI agents.
+
+Punk sits between your agent and model/tool providers. It gives existing agent apps trace IDs, route explanations, caching, governance, feedback, evidence packets, and optimization telemetry without requiring a rewrite.
+
+This repository contains the public client boundary only: SDK source, types, examples, and developer docs. The hosted Punk runtime, optimizer, learning system, replay/shadow infrastructure, governance implementation, dashboard, and deployment code are not part of this repo.
+
+## Install
+
+```bash
+npm install @punktechnologies/sdk
+# or
+bun add @punktechnologies/sdk
+```
+
+Set your gateway URL and API key:
+
+```bash
+export PUNK_BASE_URL=https://api.punktechnologies.com
+export PUNK_API_KEY=pk_...
+```
+
+For local development against a private gateway:
+
+```bash
+export PUNK_BASE_URL=http://localhost:4100
+```
+
+## One-Line Gateway Integration
+
+You do not need this SDK for the first integration. Existing OpenAI-compatible clients can route through Punk by changing `baseURL`:
+
+```ts
+import OpenAI from "openai";
+
+const root = process.env.PUNK_BASE_URL ?? "https://api.punktechnologies.com";
+
+const client = new OpenAI({
+  baseURL: `${root.replace(/\/$/, "")}/v1`,
+  apiKey: process.env.PUNK_API_KEY,
+  defaultHeaders: {
+    "X-Punk-App": "support-app",
+    "X-Punk-Agent": "triage-agent",
+    "X-Punk-Subject": "user-123"
+  }
+});
+
+const { data, response } = await client.chat.completions
+  .create({
+    model: "gpt-4o",
+    messages: [{ role: "user", content: "Classify this ticket: refund request" }]
+  })
+  .withResponse();
+
+console.log(response.headers.get("x-punk-run-id"));
+console.log(response.headers.get("x-punk-route"));
+console.log(data.choices[0]?.message?.content);
+```
+
+The same pattern works with Anthropic SDK, Vercel AI SDK, LangChain, raw HTTP, and other OpenAI-compatible clients. See [`examples/`](examples/).
+
+## Native SDK
+
+Use `@punktechnologies/sdk` when you want client helpers for tracing tools, feedback, SOM web fetches, route/evidence reads, learning state, and MCP registry operations.
+
+```ts
+import { Punk } from "@punktechnologies/sdk";
+
+const punk = new Punk({
+  baseUrl: process.env.PUNK_BASE_URL,
+  apiKey: process.env.PUNK_API_KEY,
+  app: "support-app",
+  agent: "triage-agent",
+  subject: "user-123"
+});
+
+const result = await punk.chat({
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Classify this ticket: refund request" }]
+});
+
+console.log(result.content);
+console.log(result.route);
+console.log(result.runId);
+```
+
+### Trace Tools
+
+Declare side-effect levels so Punk can cache safe reads and account for writes:
+
+```ts
+const lookupAccount = punk.traceTool({
+  name: "crm.lookupAccount",
+  sideEffectLevel: 1,
+  ttlSeconds: 300,
+  execute: async (args: { accountId: string }) => crm.get(args.accountId)
+});
+
+const account = await lookupAccount({ accountId: "acct_123" }, { runId: result.runId });
+```
+
+Side-effect levels:
+
+| Level | Meaning | Example |
+| --- | --- | --- |
+| 0 | Pure computation | parse, format, score |
+| 1 | Read-only external | search, CRM read, fetch |
+| 2 | Reversible/idempotent write | idempotent upsert |
+| 3 | User-visible write | email, Slack, ticket create |
+| 4 | High-impact write | payment, deletion, permissions |
+
+Undeclared tools default to level 3. Levels 0-1 with a TTL can participate in tool-result caching. Levels 2-4 emit planned/executed side-effect telemetry around execution.
+
+### Read Evidence
+
+```ts
+await punk.feedback(result.runId, 1);
+
+const detail = await punk.runDetail(result.runId);
+console.log(detail.run.routeExplanation);
+
+const savings = await punk.savings();
+console.log(savings.totalSavedUsd);
+```
+
+### Punk Chorus
+
+Punk Chorus is selected with `model: "punk/chorus"` on the same gateway wire:
+
+```ts
+import { Punk, punkChorusChat } from "@punktechnologies/sdk";
+
+const answer = await punk.chat(punkChorusChat({
+  messages: [{ role: "user", content: "Answer with evidence and a receipt." }],
+  budget_limit_usd: 0.25,
+  latency_mode: "balanced",
+  quality_mode: "maximum_quality",
+  receipt_mode: "full",
+  research_mode: "som"
+}));
+
+const receipt = await punk.receipt(answer.runId);
+```
+
+## Repository Contents
+
+```text
+src/        SDK source and public types
+test/       SDK behavior tests
+examples/   integration examples for common agent stacks
+docs/       SDK reference
+```
+
+## Development
+
+```bash
+bun install
+bun run test
+bun run build
+bun run typecheck
+bun run pack:check
+```
+
+The package is dependency-free at runtime and supports Node.js 18+ and Bun.
+
+## Security
+
+Security reports go to security@punktechnologies.com. Do not disclose vulnerabilities, secrets, customer data, or governance bypasses in public issues.

package/dist/index.d.ts

@@ -0,0 +1,334 @@
+/**
+ * @punktechnologies/sdk — developer-facing client for the Punk gateway.
+ *
+ * Point your agent's gateway traffic at Punk, wrap your tools with
+ * `traceTool`, and the runtime observes, caches, learns and (after replay +
+ * shadow proof) routes repeated work through deterministic artifacts.
+ */
+import type { Artifact, ArtifactEvaluation, McpServerRecord, McpTestResult, Pattern, PromotionGateStatus, Run, SavingsSummary, SideEffectLevel, SideEffectRecord, SomDiff, SomSnapshot, TraceEvent, TraceEventType, TrustLane, WebActionIntent, WebActionResult } from "./types";
+export type * from "./types";
+export interface PunkOptions {
+    /** Gateway base URL. Default: http://localhost:4100 */
+    baseUrl?: string;
+    /** Bearer token (only needed when the gateway sets PUNK_API_KEY). */
+    apiKey?: string;
+    /** Logical application name, sent as X-Punk-App. Default: "default-app". */
+    app?: string;
+    /** Agent identity, sent as X-Punk-Agent. */
+    agent?: string;
+    /** Pseudonymous end-user identifier, sent as X-Punk-Subject. */
+    subject?: string;
+}
+export declare const PUNK_CHORUS_MODEL: "punk/chorus";
+/** @deprecated Use PUNK_CHORUS_MODEL. */
+export declare const PUNK_MODEL: "punk/chorus";
+export type PunkLatencyMode = "fast" | "balanced" | "deep" | "maximum_quality" | (string & {});
+export type PunkQualityMode = "economy" | "balanced" | "frontier_optional" | "maximum_quality" | (string & {});
+export type PunkReceiptMode = "off" | "none" | "summary" | "full" | (string & {});
+export type PunkCircuitMode = "off" | "reuse" | "learn" | (string & {});
+export type PunkAuditLevel = "minimal" | "standard" | "full" | (string & {});
+export type PunkResearchMode = "off" | "som" | "plasmate" | "deep" | (string & {});
+export type PunkModelClass = "commercial" | "frontier" | "open_weight" | "local" | (string & {});
+export interface PunkChorusMetadata {
+    requestId?: string;
+    workflowId?: string;
+    tenantHint?: string;
+    labels?: string[];
+    [key: string]: unknown;
+}
+export interface PunkChorusOptions {
+    budget_limit_usd?: number;
+    latency_mode?: PunkLatencyMode;
+    quality_mode?: PunkQualityMode;
+    policy_profile?: string;
+    receipt_mode?: PunkReceiptMode;
+    circuit_mode?: PunkCircuitMode;
+    shadow_mode?: boolean;
+    audit_level?: PunkAuditLevel;
+    /** Enable the governed SOTA mix preset for maximum-quality Chorus runs. */
+    sota_mix?: boolean;
+    research_mode?: PunkResearchMode;
+    research_max_queries?: number;
+    research_max_sources?: number;
+    research_context_chars?: number;
+    live_panel_models?: string[] | string;
+    live_synthesis_model?: string;
+    live_synthesis_required?: boolean;
+    live_synthesis_max_tokens?: number;
+    /** Compatibility alias for live_synthesis_model. */
+    answer_model?: string;
+    /** Compatibility alias for live_synthesis_max_tokens. */
+    answer_max_tokens?: number;
+    local_only?: boolean;
+    allowed_model_classes?: PunkModelClass[];
+    blocked_providers?: string[];
+    /** Punk Chorus metadata forwarded in the OpenAI-compatible request body. */
+    chorus?: PunkChorusMetadata;
+}
+export interface ChatParams extends PunkChorusOptions {
+    model: string;
+    messages: Array<{
+        role: string;
+        content: string;
+    }>;
+    temperature?: number;
+    max_tokens?: number;
+    max_completion_tokens?: number;
+    top_p?: number;
+    response_format?: unknown;
+    tools?: ChatTool[];
+    tool_choice?: unknown;
+}
+export interface ChatTool {
+    type?: "function";
+    function?: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+        sideEffectLevel?: SideEffectLevel;
+        ttlSeconds?: number;
+    };
+    name?: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    sideEffectLevel?: SideEffectLevel;
+    ttlSeconds?: number;
+}
+export interface ChatToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ChatResult {
+    content: string;
+    toolCalls: ChatToolCall[];
+    runId: string;
+    route: string;
+    raw: any;
+}
+export interface PunkReceipt {
+    id?: string;
+    runId?: string;
+    route?: string;
+    chorus?: PunkChorusMetadata;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface EvidencePacket {
+    punkEvidencePacket?: number;
+    summary?: Record<string, unknown>;
+    routeExplanation?: unknown;
+    events?: unknown[];
+    chorus?: PunkChorusMetadata;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface WebFetchResult {
+    som: SomSnapshot;
+    source: string;
+    cached: boolean;
+    /** Canonical observed URL after redirects and fragment normalization. */
+    url: string;
+    /** Caller-supplied URL after server-side trim/canonicalization, before redirects. */
+    requestedUrl: string;
+    htmlBytes: number;
+    somBytes: number;
+    tokensSavedEstimate: number;
+    diff?: SomDiff;
+    context: string;
+}
+export interface WebSessionSummary {
+    id: string;
+    url: string;
+    source: string;
+    openedAt: number;
+    ageMs: number;
+}
+export interface WebSessionOpenResult {
+    sessionId: string;
+    som: SomSnapshot;
+    source: string;
+    session: WebSessionSummary;
+    context: string;
+}
+export interface WebActResult {
+    result: WebActionResult;
+    som: SomSnapshot;
+    diff?: SomDiff;
+    session: WebSessionSummary;
+    context: string;
+}
+export interface LearningReport {
+    artifactsSynthesized: number;
+    promotionsEligible: string[];
+    autoPromoted: string[];
+    synthesisReports?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+export interface RunDetail {
+    run: Run;
+    events: TraceEvent[];
+    sideEffects: SideEffectRecord[];
+}
+export interface ArtifactDetail {
+    artifact: Artifact;
+    evaluations: ArtifactEvaluation[];
+    pattern: Pattern | null;
+    promotionGate?: PromotionGateStatus;
+}
+export interface CacheStats {
+    stats: Array<{
+        cacheType: string;
+        entries: number;
+        hits: number;
+    }>;
+}
+export interface ToolDefinition<TArgs, TResult> {
+    name: string;
+    /** 0 pure … 4 high-impact. Undeclared tools are treated as level 3 (conservative). */
+    sideEffectLevel?: SideEffectLevel;
+    /** Read-only tools (level <= 1) with a TTL participate in the tool-result cache. */
+    ttlSeconds?: number;
+    /** Optional schema/version fingerprint used to isolate tool-result cache entries across contract changes. */
+    schemaFp?: string;
+    execute: (args: TArgs) => Promise<TResult> | TResult;
+}
+export type TracedTool<TArgs, TResult> = (args: TArgs, ctx?: {
+    runId?: string;
+}) => Promise<TResult>;
+export declare function punkChorusChat(params: Omit<ChatParams, "model"> & {
+    model?: typeof PUNK_CHORUS_MODEL;
+}): ChatParams;
+/** @deprecated Use punkChorusChat. */
+export declare const punkModelChat: typeof punkChorusChat;
+export declare class Punk {
+    readonly baseUrl: string;
+    readonly app: string;
+    readonly agent?: string;
+    readonly subject?: string;
+    private readonly apiKey?;
+    constructor(opts?: PunkOptions);
+    /** Send an OpenAI-compatible chat completion through the gateway. */
+    chat(params: ChatParams): Promise<ChatResult>;
+    /**
+     * Wrap a tool so every invocation is traced into the run it belongs to, and
+     * explicitly declared read-only results (level <= 1 with a TTL) flow
+     * through the tool-result cache. Tracing requires `ctx.runId`; without it
+     * the tool still executes, silently untraced and uncached.
+     */
+    traceTool<TArgs, TResult>(def: ToolDefinition<TArgs, TResult>): TracedTool<TArgs, TResult>;
+    /** Append a trace event to a run. */
+    trace(runId: string, type: TraceEventType | string, payload: Record<string, unknown>): Promise<void>;
+    feedback(runId: string, rating: 1 | -1, correction?: string): Promise<void>;
+    fetchSom(url: string, opts?: {
+        bypassCache?: boolean;
+    }): Promise<WebFetchResult>;
+    /**
+     * Web sessions & actions — the perception→action loop. Open a session,
+     * act on SOM element ids (click/type/select/submit), close it. Actions are
+     * policy-governed server-side: type/select and read-only clicks are
+     * "read:web" (side-effect level 0–1); submit and submit-button clicks are
+     * "write:web" at level 3 and can be denied/held by policy (403).
+     * Observe-mode keys cannot perform web writes.
+     */
+    readonly web: {
+        openSession: (url: string) => Promise<WebSessionOpenResult>;
+        act: (sessionId: string, intent: WebActionIntent) => Promise<WebActResult>;
+        closeSession: (sessionId: string) => Promise<{
+            ok: true;
+        }>;
+        listSessions: () => Promise<{
+            sessions: WebSessionSummary[];
+        }>;
+    };
+    /**
+     * The gateway's external-MCP registry: register servers (admin), test
+     * connections (connect + list_tools), and let workflow tool_call nodes use
+     * them. Note: stdio servers execute their command on the GATEWAY host —
+     * registration is an operator-level action.
+     */
+    readonly mcp: {
+        listServers: () => Promise<McpServerRecord[]>;
+        createServer: (server: {
+            name: string;
+            transport: "stdio" | "http";
+            command?: string;
+            args?: string[];
+            url?: string;
+            /** Values may be cred:<credentialId> references (resolved at connect time). */
+            env?: Record<string, string>;
+            headers?: Record<string, string>;
+            enabled?: boolean;
+        }) => Promise<McpServerRecord>;
+        /** Connect + list_tools (throwaway connection); persists the server's status. */
+        testServer: (id: string) => Promise<McpTestResult>;
+    };
+    /**
+     * Declare what memory/context influenced a run, tagged with its trust lane.
+     * Recording is ALWAYS allowed (cheap, useful telemetry). When the tenant
+     * enables memory quarantine, low-trust influence (untrusted/observed) on a
+     * run gates that run's high-impact (side-effect ≥ threshold) actions to
+     * approval_required — "untrusted web content can't trigger a payment".
+     */
+    readonly memory: {
+        recordInfluence: (runId: string, influence: {
+            source: string;
+            trustLane: TrustLane;
+            contentHash?: string;
+        }) => Promise<{
+            ok: boolean;
+            influence: {
+                id: string;
+                runId: string;
+                source: string;
+                trustLane: TrustLane;
+            };
+        }>;
+    };
+    /**
+     * Ingest an externally-handled prompt (Claude Code / Claude app / any
+     * client) as a completed OBSERVED run: $0 cost, model "external", redaction
+     * honored. Returns the created run id.
+     */
+    ingestPrompt(source: string, prompt: string, opts?: {
+        sessionId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        runId: string;
+    }>;
+    savings(): Promise<SavingsSummary>;
+    patterns(): Promise<Pattern[]>;
+    artifacts(): Promise<Artifact[]>;
+    artifactDetail(id: string): Promise<ArtifactDetail>;
+    runDetail(id: string): Promise<RunDetail>;
+    receipt(id: string): Promise<PunkReceipt>;
+    evidencePacket(runId: string): Promise<EvidencePacket>;
+    cacheStats(): Promise<CacheStats>;
+    learningTick(): Promise<LearningReport>;
+    promoteArtifact(id: string): Promise<Artifact>;
+    /** Best-effort cache lookup; network failures degrade to a miss. */
+    toolCacheCheck(toolName: string, args: unknown, sideEffectLevel?: SideEffectLevel, schemaFp?: string): Promise<{
+        hit: boolean;
+        result?: unknown;
+    }>;
+    /** Best-effort cache store; failures are swallowed. */
+    toolCacheStore(toolName: string, args: unknown, result: unknown, ttlSeconds?: number, sideEffectLevel?: SideEffectLevel, schemaFp?: string): Promise<void>;
+    private headers;
+    private request;
+    private parseJsonResponse;
+    private toError;
+    private toTransportError;
+    private responseErrorMessage;
+    /** Tracing is observability, not control flow — failures are swallowed. */
+    private tryTrace;
+    /**
+     * Trace a tool call and return Punk's governance decision when one is
+     * provided. Transport/API failures still fail open so telemetry outages do
+     * not break tools; explicit deny/approval decisions remain control flow.
+     */
+    private tryTraceDecision;
+}
+export default Punk;