@punktechnologies/sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,346 @@
+/**
+ * @punktechnologies/sdk — local type contracts.
+ *
+ * These mirror the canonical definitions in `@punk/trace-schema` (the
+ * dependency-free contract package every Punk service imports). They are
+ * copied here — not imported — so the published SDK has zero dependencies.
+ *
+ * If a shape changes in `@punk/trace-schema`, update the mirror here.
+ * The gateway is the source of truth at runtime; these types describe what
+ * its API returns.
+ */
+/** MeshGuard-compatible trust tiers. */
+export type TrustTier = "unverified" | "verified" | "trusted" | "privileged";
+/** Trust lane of a memory/context source (memory quarantine). */
+export type TrustLane = "untrusted" | "observed" | "verified" | "human_approved";
+/**
+ * 0 pure computation, 1 read-only external, 2 reversible/idempotent writes,
+ * 3 user-visible writes (slack/email/tickets), 4 high-impact (payments,
+ * deletion, permissions). Undeclared tools default to level 3 (conservative).
+ */
+export type SideEffectLevel = 0 | 1 | 2 | 3 | 4;
+export type SideEffectStatus = "planned" | "executed" | "suppressed" | "dry_run" | "blocked";
+export interface SideEffectRecord {
+    id: string;
+    runId: string;
+    tenantId: string;
+    toolName: string;
+    level: SideEffectLevel;
+    status: SideEffectStatus;
+    idempotencyKey?: string;
+    payload?: unknown;
+    createdAt: number;
+}
+export type RouteType = "live" | "exact_cache" | "semantic_cache" | "tool_cache" | "som_cache" | "plan_cache" | "artifact" | "hybrid_artifact" | "model_substitution" | "chorus" | "blocked";
+export interface RouteAlternative {
+    route: RouteType;
+    rejected: string;
+}
+export interface PolicyVerdict {
+    decision: "allow" | "deny" | "approval_required";
+    policyName?: string;
+    ruleIndex?: number;
+    reason: string;
+    trustTier?: TrustTier;
+    sideEffectLevel?: SideEffectLevel;
+}
+/** Every optimized response must be explainable. */
+export interface RouteExplanation {
+    route: RouteType;
+    reason: string;
+    alternatives: RouteAlternative[];
+    policy?: PolicyVerdict;
+    cache?: {
+        type: string;
+        hit: boolean;
+        key?: string;
+        freshness?: "valid" | "stale" | "expired";
+        ageMs?: number;
+    };
+    artifact?: {
+        id: string;
+        version: number;
+        confidence: number;
+        shadowed?: boolean;
+    };
+    pattern?: {
+        id: string;
+        name: string;
+        confidence: number;
+    };
+    estimatedSavedUsd?: number;
+    estimatedSavedMs?: number;
+    /**
+     * Observe-mode ghost accounting: what the optimizer WOULD have done.
+     * Present only when the API key runs in "observe" mode and a
+     * cheaper/blocked route existed.
+     */
+    ghost?: {
+        route: RouteType | "blocked";
+        estimatedSavedUsd: number;
+        estimatedSavedMs: number;
+        reason: string;
+    };
+    fallback: string;
+}
+export type RunStatus = "running" | "completed" | "failed" | "blocked";
+export interface Run {
+    id: string;
+    tenantId: string;
+    appId: string;
+    agentId?: string;
+    /** Pseudonymous subject (end user) identifier. */
+    subject?: string;
+    status: RunStatus;
+    route?: RouteType;
+    shadowed?: boolean;
+    requestHash: string;
+    /** Normalized prompt-shape fingerprint; groups runs into patterns. */
+    fingerprint?: string;
+    patternId?: string;
+    provider?: string;
+    model?: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    /** Estimated USD avoided versus the live path (0 for live runs). */
+    savedUsd: number;
+    /** Observe mode: estimated USD Punk WOULD have saved (ghost accounting). */
+    ghostSavedUsd?: number;
+    latencyMs: number;
+    startedAt: number;
+    completedAt?: number;
+    routeExplanation?: RouteExplanation;
+    error?: string;
+}
+export type TraceEventType = "request.received" | "policy.checked" | "route.selected" | "model.requested" | "model.failover" | "model.completed" | "chorus.contract" | "chorus.claim_graph" | "chorus.route_selected" | "chorus.verifier" | "chorus.auction" | "chorus.ledger" | "chorus.research_pack" | "chorus.live_synthesis" | "chorus.live_synthesis_empty" | "chorus.live_synthesis_failed" | "chorus.receipt" | "tool.called" | "tool.completed" | "web.fetched" | "som.compiled" | "som.cache_hit" | "som.diffed" | "web.acted" | "side_effect.planned" | "side_effect.executed" | "side_effect.suppressed" | "side_effect.blocked" | "cache.checked" | "cache.hit" | "cache.miss" | "cache.stored" | "artifact.selected" | "artifact.executed" | "artifact.failed" | "artifact.shadowed" | "evaluator.scored" | "pattern.updated" | "artifact.synthesized" | "artifact.state_changed" | "drift.detected" | "tripwire.fired" | "user.feedback" | "run.completed";
+export interface TraceEvent {
+    id: string;
+    runId: string;
+    tenantId: string;
+    type: TraceEventType;
+    ts: number;
+    parentId?: string;
+    payload: Record<string, unknown>;
+    schemaVersion: 1;
+}
+export type PatternState = "observed" | "candidate" | "watchlisted" | "synthesizing" | "replay_tested" | "shadowing" | "promoted" | "negative" | "retired";
+export type TaskClass = "deterministic" | "schema_deterministic" | "semantic" | "preference" | "open_ended" | "high_risk";
+export interface Pattern {
+    id: string;
+    tenantId: string;
+    appId: string;
+    name: string;
+    state: PatternState;
+    /** Normalized prompt-shape fingerprint (primary cluster key). */
+    fingerprint: string;
+    toolSequenceFp?: string;
+    outputSchemaFp?: string;
+    taskClass: TaskClass;
+    riskLevel: SideEffectLevel;
+    runCount: number;
+    totalCostUsd: number;
+    avgCostUsd: number;
+    avgLatencyMs: number;
+    /** How stable inputs→outputs are across observed runs, [0,1]. */
+    stabilityScore: number;
+    /** expected_value-style prioritization score. */
+    optimizableScore: number;
+    exampleRunIds: string[];
+    negativeReason?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export type ArtifactState = "candidate" | "replay_failed" | "replay_passed" | "shadowing" | "shadow_failed" | "approved" | "promoted" | "canary" | "stable" | "degraded" | "quarantined" | "retired";
+export type ArtifactType = "static_response" | "template" | "deterministic_transform" | "ruleset_classifier" | "tool_plan" | "web_extraction" | "hybrid";
+/**
+ * Loose representation slot; the gateway's artifact runtime defines and
+ * validates the concrete declarative DSL.
+ */
+export type ArtifactRepresentation = {
+    dslVersion: 1;
+    kind: ArtifactType;
+} & Record<string, unknown>;
+export interface ArtifactProvenance {
+    synthesizer: string;
+    sourceRunIds: string[];
+    holdoutRunIds: string[];
+    parentArtifactId?: string;
+    notes?: string;
+}
+export interface Artifact {
+    id: string;
+    tenantId: string;
+    patternId: string;
+    version: number;
+    type: ArtifactType;
+    state: ArtifactState;
+    representation: ArtifactRepresentation;
+    provenance: ArtifactProvenance;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    sideEffectLevel: SideEffectLevel;
+    /** Successes + prior. Updated on every replay/shadow/live evaluation. */
+    alpha: number;
+    /** Failures + prior. */
+    beta: number;
+    /** Lower-bound confidence derived from the posterior; the router gates on this. */
+    confidence: number;
+    replayPasses: number;
+    replayFails: number;
+    shadowPasses: number;
+    shadowFails: number;
+    livePasses: number;
+    liveFails: number;
+    estCostUsd: number;
+    estLatencyMs: number;
+    createdAt: number;
+    promotedAt?: number;
+    lastEvaluatedAt?: number;
+    stateReason?: string;
+}
+export interface PromotionGateStatus {
+    eligible: boolean;
+    autoPromotable: boolean;
+    reasons: string[];
+}
+export type EvaluationKind = "replay" | "shadow" | "live";
+export interface ArtifactEvaluation {
+    id: string;
+    artifactId: string;
+    tenantId: string;
+    kind: EvaluationKind;
+    runId?: string;
+    pass: boolean;
+    structuralPass: boolean;
+    semanticScore: number;
+    sideEffectPass: boolean;
+    expected?: string;
+    actual?: string;
+    details?: string;
+    createdAt: number;
+}
+/** Mirrors Plasmate's Som struct (som_version "0.1"). */
+export interface SomSnapshot {
+    som_version: string;
+    url: string;
+    title: string;
+    lang: string;
+    regions: SomRegion[];
+    meta: {
+        html_bytes: number;
+        som_bytes: number;
+        element_count: number;
+        interactive_count: number;
+    };
+}
+export interface SomRegion {
+    id: string;
+    role: string;
+    label?: string;
+    action?: string;
+    method?: string;
+    elements: SomElement[];
+}
+export interface SomElement {
+    id: string;
+    role: string;
+    text?: string;
+    label?: string;
+    actions?: string[];
+    attrs?: Record<string, unknown>;
+    children?: SomElement[];
+}
+export interface SomDiffEntry {
+    kind: "added" | "removed" | "changed";
+    regionId: string;
+    elementId?: string;
+    field?: string;
+    before?: string;
+    after?: string;
+    /** Semantic weight: pricing/CTA/form changes matter more than footer noise. */
+    significance: "high" | "medium" | "low";
+}
+export interface SomDiff {
+    url: string;
+    beforeFingerprint: string;
+    afterFingerprint: string;
+    entries: SomDiffEntry[];
+    /** Aggregate drift signal in [0,1]. */
+    driftScore: number;
+}
+/** Protocol-level actions an agent can take on a SOM page (no JS engine). */
+export type WebActionKind = "click" | "type" | "select" | "submit";
+export interface WebActionIntent {
+    action: WebActionKind;
+    /** SOM element id (e_…) — or a region id (r_form…) for submit. */
+    target: string;
+    value?: string;
+}
+export interface WebActionResult {
+    ok: boolean;
+    action: WebActionKind;
+    target: string;
+    /** Element/region id the engine resolved the target to. */
+    resolved?: string;
+    /** True when the action caused a page navigation (link follow / form submit). */
+    navigated?: boolean;
+    /** Page URL after the action. */
+    url: string;
+    /** URL the action attempted before redirects, when it caused navigation. */
+    requestedUrl?: string;
+    error?: string;
+    /**
+     * For successful form submissions, including submit-button clicks: the
+     * serialized field set that was posted (name -> value), so the operator can
+     * see exactly what was sent.
+     */
+    posted?: Record<string, string>;
+}
+export interface SavingsSummary {
+    tenantId: string;
+    totalRuns: number;
+    liveRuns: number;
+    optimizedRuns: number;
+    blockedRuns: number;
+    totalCostUsd: number;
+    totalSavedUsd: number;
+    /** Observe-mode ghost accounting: sum of per-run ghostSavedUsd. */
+    ghostSavedUsd: number;
+    totalSavedMs: number;
+    cacheHits: number;
+    artifactHits: number;
+    cacheHitRate: number;
+    artifactHitRate: number;
+    somTokensSaved: number;
+}
+export interface McpServerRecord {
+    id: string;
+    tenantId: string;
+    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;
+    status: "unknown" | "ok" | "error";
+    lastTestedAt?: number;
+    lastError?: string;
+    toolCount: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface McpTestResult {
+    ok: boolean;
+    toolCount?: number;
+    tools?: Array<{
+        name: string;
+        description?: string;
+        inputSchema?: unknown;
+    }>;
+    error?: string;
+    latencyMs: number;
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@punktechnologies/sdk",
+  "version": "0.1.0",
+  "description": "Dependency-free TypeScript SDK for Punk, the adaptive runtime for production AI agents.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "packageManager": "bun@1.3.5",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node --format esm && tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "pack:check": "npm pack --dry-run",
+    "prepack": "bun run build",
+    "prepublishOnly": "bun run build && bun run test && bun run typecheck"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PunkTechnologies/punk-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PunkTechnologies/punk-sdk/issues"
+  },
+  "homepage": "https://punktechnologies.com",
+  "keywords": [
+    "ai",
+    "agents",
+    "llm",
+    "gateway",
+    "openai-compatible",
+    "anthropic",
+    "caching",
+    "tracing",
+    "observability",
+    "governance",
+    "side-effects",
+    "punk"
+  ],
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "@types/node": "^25.9.2",
+    "typescript": "^5.7.0"
+  }
+}