@sudobility/sider_types 0.0.2

package/dist/actions.d.ts

@@ -0,0 +1,29 @@
+export type OutcomeCategory = "gate" | "http" | "not_found" | "no_effect" | "precondition";
+export interface ActionOutcome {
+    /** ok = did what was asked; blocked = known reportable refusal; failed = unexpected. */
+    status: "ok" | "blocked" | "failed";
+    /** Closed mechanism vocabulary (branch/color on this). */
+    category?: OutcomeCategory;
+    /** OPEN, domain-agnostic reason slug: "gate_same_origin", "pre_order",
+     *  "already_following", "login_required", … Not an enum. */
+    reason?: string;
+    /** Human-readable detail / evidence. */
+    detail?: string;
+    /** Tokenized + size-capped payload on ok (read items / response body). */
+    data?: unknown;
+}
+/** One item extracted from a rendered result collection by readPage. */
+export interface ExtractedItem {
+    title: string;
+    price?: string;
+    url?: string;
+    /** Availability phrase found near the item ("pre-order", "out of stock"); absent = available. */
+    availability?: string;
+    imageUrl?: string;
+    /** href when present, else a resolved unique selector — used to open/click the item. */
+    ref: string;
+}
+export interface ReadPageResult {
+    items: ExtractedItem[];
+    count: number;
+}

package/dist/actions.js

@@ -0,0 +1,4 @@
+// Structured results for the three model-facing browser actions (callSiderTool,
+// readPage, siderDomAction). One shape so the agent can aggregate outcomes and
+// report a status summary (e.g. "added 3/5; 2 pre-order only").
+export {};

package/dist/api.d.ts

@@ -0,0 +1,54 @@
+import type { EndpointGraphEdge, SafetyClass, SecretSlot, Site, ToolSpec, UXRecipe } from "./registry";
+import type { Observation, StepKind } from "./runtime";
+/** A planner decision (mirror of the ShapeShyft plan-next-step output). */
+export interface PlannerStep {
+    kind: StepKind;
+    toolId?: string;
+    args?: Record<string, unknown>;
+    safetyClass?: SafetyClass;
+    rationale?: string;
+    domAction?: {
+        type: "hover" | "click" | "type";
+        selector: string;
+        text?: string;
+    };
+    askPrompt?: string;
+}
+export interface SiteLookupResult {
+    known: boolean;
+    site?: Site;
+    hasTrustedTools?: boolean;
+}
+/** The MCP tool catalog served for a site (placeholder-only, safe to share). */
+export interface ToolCatalog {
+    tools: ToolSpec[];
+    secretSlots: SecretSlot[];
+    edges: EndpointGraphEdge[];
+    uxRecipes: UXRecipe[];
+}
+export type ObservationUpload = Omit<Observation, "id" | "batchId" | "createdAt">;
+export type SecretSlotUpload = Omit<SecretSlot, "siteId" | "createdAt" | "updatedAt">;
+export interface CaptureRequest {
+    siteOrigin: string;
+    siteName?: string;
+    observations: ObservationUpload[];
+    secretSlots?: SecretSlotUpload[];
+}
+export interface CaptureResponse {
+    batchId: string;
+    siteId: string;
+}
+export interface PlanStartResponse {
+    runId: string;
+    step: PlannerStep;
+}
+export interface PlanStepResponse {
+    step: PlannerStep;
+}
+/** Public aggregate stats for the marketing site. */
+export interface StatsResponse {
+    siteCount: number;
+    toolCount: number;
+    trustedToolCount: number;
+    contributorCount: number;
+}

package/dist/api.js

@@ -0,0 +1,4 @@
+// Wire contract for sider_api — the request/response DTOs shared by the server
+// (to type its handlers) and sider_client (to type its calls). Keeping these
+// here is the single source of truth that stops the two sides from drifting.
+export {};

package/dist/common.d.ts

@@ -0,0 +1,28 @@
+/** ISO-8601 timestamp string. */
+export type IsoTimestamp = string;
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+/**
+ * Minimal JSON Schema representation. Sider stores inferred request/response
+ * shapes and tool input schemas as JSON Schema so they are portable to MCP.
+ */
+export interface JSONSchema {
+    type?: "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
+    properties?: Record<string, JSONSchema>;
+    items?: JSONSchema;
+    required?: string[];
+    enum?: unknown[];
+    const?: unknown;
+    description?: string;
+    format?: string;
+    [k: string]: unknown;
+}
+/** Standard success/error envelope returned by sider_api. */
+export type ApiResponse<T> = {
+    success: true;
+    data: T;
+    timestamp: IsoTimestamp;
+} | {
+    success: false;
+    error: string;
+    timestamp: IsoTimestamp;
+};

package/dist/common.js

@@ -0,0 +1,2 @@
+// Common primitives shared across all Sider tiers.
+export {};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./common";
+export * from "./registry";
+export * from "./runtime";
+export * from "./local";
+export * from "./api";
+export * from "./actions";

package/dist/index.js

@@ -0,0 +1,12 @@
+// @sudobility/sider_types — shared domain types for Sider.
+//
+// Three tiers, one hard rule: a plaintext secret exists in exactly ONE of them.
+//   - GLOBAL  (registry.ts): shared across all users; placeholders only.
+//   - PRIVATE (runtime.ts):  per-user server data; uploaded already tokenized.
+//   - LOCAL   (local.ts):    browser only; the sole holder of real secret values.
+export * from "./common";
+export * from "./registry";
+export * from "./runtime";
+export * from "./local";
+export * from "./api";
+export * from "./actions";

package/dist/local.d.ts

@@ -0,0 +1,20 @@
+import type { IsoTimestamp } from "./common";
+import type { ResolverHint } from "./registry";
+/**
+ * Maps a global SecretSlot to how its value is found in THIS user's session,
+ * and (transiently) to the value itself.
+ *
+ * `currentValue` is the ONLY field in the entire Sider type system that may
+ * hold a plaintext secret. It exists only in the tab that already legitimately
+ * holds the user's own credential, is read fresh at egress, and is never
+ * persisted to disk or transmitted anywhere.
+ */
+export interface TokenMapEntry {
+    /** Matches a global SecretSlot.id. */
+    slotId: string;
+    /** The hint that actually resolved a value in this session. */
+    resolver: ResolverHint;
+    /** Read fresh at egress; never persisted or transmitted. */
+    currentValue?: string;
+    lastSeenAt: IsoTimestamp;
+}

package/dist/local.js

@@ -0,0 +1,8 @@
+// ============================================================================
+// LOCAL TIER — browser only.
+//
+// Nothing in this file is EVER uploaded to sider_api, written to a server
+// database, or placed in an LLM prompt. It lives in chrome.storage.session
+// (per-tab, cleared on close) and in memory.
+// ============================================================================
+export {};

package/dist/registry.d.ts

@@ -0,0 +1,215 @@
+import type { HttpMethod, IsoTimestamp, JSONSchema } from "./common";
+export interface SitePolicy {
+    /** If true, Sider is disabled on this origin (denylist: banking/health/etc.). */
+    blocked: boolean;
+    /** Whether the assistant may perform write/financial actions on this site. */
+    allowMutations: boolean;
+    /** Rate cap applied to Sider-issued requests on this origin. */
+    maxRequestsPerMinute: number;
+}
+export interface Site {
+    id: string;
+    /** Scheme + host (+ port). The trust/same-origin boundary. */
+    origin: string;
+    name: string;
+    policy: SitePolicy;
+    toolCount: number;
+    trustedToolCount: number;
+    contributorCount: number;
+    createdAt: IsoTimestamp;
+    updatedAt: IsoTimestamp;
+}
+export type EndpointCategory = "read" | "write" | "auth" | "telemetry" | "unknown";
+export interface FieldSemantics {
+    /** JSON path within the request or response (e.g. "data.sections[].price"). */
+    jsonPath: string;
+    meaning: string;
+    type: string;
+    /** True if this field is an identifier (candidate for a data-flow edge). */
+    isId: boolean;
+    /** If this field feeds a param of another endpoint, the target template id. */
+    linksToTemplateId?: string;
+    isPII: boolean;
+    /** If true, this field is represented by a SecretSlot rather than a raw value. */
+    isSecret: boolean;
+}
+/** Which credentials an endpoint requires — described structurally, never by value. */
+export interface AuthProfile {
+    /** SecretSlot ids that must be resolved at call time. */
+    requiredSlotIds: string[];
+    /** Header names observed carrying auth (values are never recorded). */
+    authHeaderNames: string[];
+    /** Whether the endpoint relies on cookies the browser attaches automatically. */
+    usesCookies: boolean;
+}
+export interface EndpointTemplate {
+    id: string;
+    siteId: string;
+    method: HttpMethod;
+    /** Path with params extracted: "/api/sections/{sectionId}/seats". */
+    pathTemplate: string;
+    /** For GraphQL: the operation name (the URL alone is not distinguishing). */
+    graphqlOperation?: string;
+    description: string;
+    category: EndpointCategory;
+    requestSchema: JSONSchema;
+    responseSchema: JSONSchema;
+    requestFields: FieldSemantics[];
+    responseFields: FieldSemantics[];
+    authProfile: AuthProfile;
+    observationCount: number;
+    corroboratingUserCount: number;
+    confidence: number;
+    createdAt: IsoTimestamp;
+    updatedAt: IsoTimestamp;
+}
+export type SecretKind = "bearer" | "csrf" | "api_key" | "session" | "signature" | "pii" | "unknown";
+export type SecretRole = "auto_cookie" | "active_inject";
+/** WHERE a secret is allowed to be placed — enforced at egress (Gate B). */
+export type InjectionLocation = {
+    at: "header";
+    name: string;
+} | {
+    at: "query";
+    param: string;
+} | {
+    at: "body";
+    jsonPath: string;
+} | {
+    at: "cookie";
+    name: string;
+};
+/**
+ * WHERE to find the current value of a secret in the user's own session.
+ * Carries structural identifiers (cookie NAME, storage KEY, selector) only —
+ * never the value itself. Each user's browser resolves its own value.
+ */
+export type ResolverHint = {
+    from: "cookie";
+    name: string;
+} | {
+    from: "storage";
+    area: "local" | "session";
+    key: string;
+} | {
+    from: "dom";
+    selector: string;
+    attr?: string;
+} | {
+    from: "response";
+    endpointTemplateId: string;
+    jsonPath: string;
+};
+export interface SecretSlot {
+    /** Placeholder id used in recipes and tokenized samples, e.g. "site:<id>:auth_bearer". */
+    id: string;
+    siteId: string;
+    kind: SecretKind;
+    role: SecretRole;
+    injectionLocation: InjectionLocation;
+    /** Same-origin lock (Gate A): a recipe host must equal this origin to use the slot. */
+    allowedDestination: string;
+    /** Ranked structural hints for locating the current value locally. Never values. */
+    resolverHints: ResolverHint[];
+    confidence: number;
+    createdAt: IsoTimestamp;
+    updatedAt: IsoTimestamp;
+}
+export type SafetyClass = "read" | "write" | "financial";
+export type ToolStatus = "provisional" | "trusted" | "flagged";
+/** Resolves a single `{key}` placeholder used anywhere in a recipe. */
+export type ParamBinding = {
+    kind: "literal";
+    value: string;
+} | {
+    kind: "arg";
+    argName: string;
+} | {
+    kind: "secret";
+    slotId: string;
+} | {
+    kind: "priorOutput";
+    stepRef: string;
+    jsonPath: string;
+};
+export interface HeaderTemplate {
+    name: string;
+    /** May contain `{key}` placeholders resolved via InvocationRecipe.bindings. */
+    valueTemplate: string;
+}
+export interface SignatureModel {
+    type: "none" | "hmac" | "unknown";
+    /** When type !== "none", the endpoint typically cannot be replayed via a
+     *  direct call and must be driven through DOM emulation instead. */
+    note?: string;
+}
+/** One sub-call of a composite/paginating tool. */
+export interface ComposeStep {
+    /** Referenced by later `{ kind: "priorOutput", stepRef }` bindings. */
+    ref: string;
+    toolId: string;
+    argBindings: Record<string, ParamBinding>;
+    /** If set, run once per element of the array at this jsonPath in the prior
+     *  result (fan-out) — e.g. "for each section, fetch its seats". */
+    forEachJsonPath?: string;
+}
+export interface InvocationRecipe {
+    method: HttpMethod;
+    /** Path/template relative to the site origin. Placeholders: `{key}`. */
+    urlTemplate: string;
+    headers: HeaderTemplate[];
+    /** JSON body template; string values may contain `{key}` placeholders. */
+    bodyTemplate?: unknown;
+    credentials: "include";
+    /** Resolves every `{key}` used in urlTemplate / headers / bodyTemplate. */
+    bindings: Record<string, ParamBinding>;
+    signatureModel?: SignatureModel;
+    /** For composite/paginating tools: ordered sub-calls that feed later bindings. */
+    compose?: ComposeStep[];
+}
+export interface ToolSpec {
+    id: string;
+    siteId: string;
+    name: string;
+    description: string;
+    /** Short imperative user-facing label ("Search for a product"); "" = none. */
+    capabilityLabel?: string;
+    inputSchema: JSONSchema;
+    safetyClass: SafetyClass;
+    /** false ⇒ signed/HMAC or otherwise non-replayable → DOM emulation only. */
+    directCallAvailable: boolean;
+    recipe: InvocationRecipe;
+    status: ToolStatus;
+    version: number;
+    observationCount: number;
+    /** Distinct users whose learned recipe corroborated this tool (trust gate). */
+    corroboratingUserCount: number;
+    confidence: number;
+    createdAt: IsoTimestamp;
+    updatedAt: IsoTimestamp;
+}
+export interface EndpointGraphEdge {
+    id: string;
+    siteId: string;
+    fromTemplateId: string;
+    /** Field in the source response that supplies the value. */
+    fromJsonPath: string;
+    toTemplateId: string;
+    /** Param of the target endpoint that the value feeds. */
+    toParam: string;
+    confidence: number;
+}
+export interface UXRecipe {
+    id: string;
+    siteId: string;
+    /** Natural-language goal pattern this recipe serves, e.g. "find cheapest seats". */
+    goalPattern: string;
+    /** Key of a generative-UI component the extension knows how to render. */
+    componentKey: string;
+    /** How to source the component's data. */
+    binding: {
+        toolId: string;
+        argBindings: Record<string, ParamBinding>;
+    };
+    status: ToolStatus;
+}

package/dist/registry.js

@@ -0,0 +1,10 @@
+// ============================================================================
+// GLOBAL TIER — the shared registry.
+//
+// Every type in this file is shared across ALL users of a site. It therefore
+// may NEVER contain a plaintext secret. Secrets appear only as placeholder
+// references to SecretSlot ids (e.g. "{key}" bound to { kind: "secret", slotId }).
+// The plaintext value of a secret lives exclusively in the browser (see
+// ./local.ts — TokenMapEntry).
+// ============================================================================
+export {};

package/dist/runtime.d.ts

@@ -0,0 +1,96 @@
+import type { HttpMethod, IsoTimestamp } from "./common";
+import type { SafetyClass } from "./registry";
+export interface RequestContext {
+    /** Page route when the request fired. */
+    route: string;
+    /** DOM element the user interacted with just before the request, if any. */
+    triggerSelector?: string;
+    pageTitle?: string;
+}
+/**
+ * A single observed request/response.
+ *
+ * TOKENIZED: every secret value is already a "{{slot:…}}" placeholder before
+ * this object leaves the browser. Auth header values are placeholders or were
+ * dropped entirely in the browser's redaction pre-pass.
+ */
+export interface Observation {
+    id: string;
+    batchId: string;
+    /** Assigned during clustering. */
+    endpointTemplateId?: string;
+    method: HttpMethod;
+    url: string;
+    requestHeaders: Record<string, string>;
+    requestBody?: unknown;
+    status: number;
+    responseBody?: unknown;
+    timingMs: number;
+    context: RequestContext;
+    createdAt: IsoTimestamp;
+}
+export type CaptureBatchStatus = "buffering" | "uploaded" | "distilled" | "discarded";
+export interface CaptureBatch {
+    id: string;
+    contributorId: string;
+    siteId: string;
+    status: CaptureBatchStatus;
+    observationCount: number;
+    createdAt: IsoTimestamp;
+}
+export type StepKind = "tool_call" | "dom_action" | "ask_user" | "done";
+export type StepStatus = "pending" | "awaiting_confirm" | "running" | "done" | "error" | "aborted";
+export interface PlanStep {
+    id: string;
+    runId: string;
+    index: number;
+    kind: StepKind;
+    toolId?: string;
+    safetyClass?: SafetyClass;
+    /** Shape/keys of args only — never secret values. */
+    argsShape?: unknown;
+    status: StepStatus;
+    /** Shape of the result — never secret values. */
+    resultShape?: unknown;
+    rationale?: string;
+    error?: string;
+    startedAt?: IsoTimestamp;
+    finishedAt?: IsoTimestamp;
+}
+export type PlanRunStatus = "planning" | "awaiting_approval" | "running" | "completed" | "aborted" | "error";
+export interface PlanRun {
+    id: string;
+    contributorId: string;
+    siteId: string;
+    goal: string;
+    status: PlanRunStatus;
+    createdAt: IsoTimestamp;
+    finishedAt?: IsoTimestamp;
+}
+export interface Contributor {
+    firebaseUid: string;
+    reputation: number;
+    createdAt: IsoTimestamp;
+}
+/**
+ * Output of sider_lib compiling a ToolSpec + args, BEFORE detokenization.
+ * Placeholders are still present; secrets are substituted only after all three
+ * egress gates pass.
+ */
+export interface CompiledRequest {
+    method: HttpMethod;
+    url: string;
+    headers: Record<string, string>;
+    body?: unknown;
+    credentials: "include";
+    referencedSlotIds: string[];
+    safetyClass: SafetyClass;
+}
+/** Result of an egress gate check (same-origin / injection-location / safety). */
+export type GateOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    gate: "same_origin" | "injection_location" | "safety";
+    reason: string;
+};

package/dist/runtime.js

@@ -0,0 +1,8 @@
+// ============================================================================
+// PRIVATE TIER (per-user server data) + browser-side execution helper types.
+//
+// Capture data reaches this tier already TOKENIZED — every secret value is a
+// placeholder before it ever leaves the browser. Plan/audit records store the
+// SHAPE of args and results, never secret values.
+// ============================================================================
+export {};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@sudobility/sider_types",
+  "version": "0.0.2",
+  "description": "Shared domain types for Sider — AI assistance for generic web apps.",
+  "license": "BUSL-1.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/actions.ts

@@ -0,0 +1,43 @@
+// Structured results for the three model-facing browser actions (callSiderTool,
+// readPage, siderDomAction). One shape so the agent can aggregate outcomes and
+// report a status summary (e.g. "added 3/5; 2 pre-order only").
+
+// Closed, mechanism-level category — what Sider's own execution can determine.
+// Domain-specific "why" lives in the open `reason`/`detail`, never here.
+export type OutcomeCategory =
+  | "gate"          // a security gate refused the request
+  | "http"          // the request returned a non-2xx status
+  | "not_found"     // the tool or DOM target was missing
+  | "no_effect"     // the action produced no observable result
+  | "precondition"; // a site-level condition blocked it (open-ended; see reason/detail)
+
+export interface ActionOutcome {
+  /** ok = did what was asked; blocked = known reportable refusal; failed = unexpected. */
+  status: "ok" | "blocked" | "failed";
+  /** Closed mechanism vocabulary (branch/color on this). */
+  category?: OutcomeCategory;
+  /** OPEN, domain-agnostic reason slug: "gate_same_origin", "pre_order",
+   *  "already_following", "login_required", … Not an enum. */
+  reason?: string;
+  /** Human-readable detail / evidence. */
+  detail?: string;
+  /** Tokenized + size-capped payload on ok (read items / response body). */
+  data?: unknown;
+}
+
+/** One item extracted from a rendered result collection by readPage. */
+export interface ExtractedItem {
+  title: string;
+  price?: string;
+  url?: string;
+  /** Availability phrase found near the item ("pre-order", "out of stock"); absent = available. */
+  availability?: string;
+  imageUrl?: string;
+  /** href when present, else a resolved unique selector — used to open/click the item. */
+  ref: string;
+}
+
+export interface ReadPageResult {
+  items: ExtractedItem[];
+  count: number;
+}

package/src/api.ts

@@ -0,0 +1,68 @@
+// Wire contract for sider_api — the request/response DTOs shared by the server
+// (to type its handlers) and sider_client (to type its calls). Keeping these
+// here is the single source of truth that stops the two sides from drifting.
+
+import type {
+  EndpointGraphEdge,
+  SafetyClass,
+  SecretSlot,
+  Site,
+  ToolSpec,
+  UXRecipe,
+} from "./registry";
+import type { Observation, StepKind } from "./runtime";
+
+/** A planner decision (mirror of the ShapeShyft plan-next-step output). */
+export interface PlannerStep {
+  kind: StepKind;
+  toolId?: string;
+  args?: Record<string, unknown>;
+  safetyClass?: SafetyClass;
+  rationale?: string;
+  domAction?: { type: "hover" | "click" | "type"; selector: string; text?: string };
+  askPrompt?: string;
+}
+
+export interface SiteLookupResult {
+  known: boolean;
+  site?: Site;
+  hasTrustedTools?: boolean;
+}
+
+/** The MCP tool catalog served for a site (placeholder-only, safe to share). */
+export interface ToolCatalog {
+  tools: ToolSpec[];
+  secretSlots: SecretSlot[];
+  edges: EndpointGraphEdge[];
+  uxRecipes: UXRecipe[];
+}
+
+export type ObservationUpload = Omit<Observation, "id" | "batchId" | "createdAt">;
+export type SecretSlotUpload = Omit<SecretSlot, "siteId" | "createdAt" | "updatedAt">;
+
+export interface CaptureRequest {
+  siteOrigin: string;
+  siteName?: string;
+  observations: ObservationUpload[];
+  secretSlots?: SecretSlotUpload[];
+}
+export interface CaptureResponse {
+  batchId: string;
+  siteId: string;
+}
+
+export interface PlanStartResponse {
+  runId: string;
+  step: PlannerStep;
+}
+export interface PlanStepResponse {
+  step: PlannerStep;
+}
+
+/** Public aggregate stats for the marketing site. */
+export interface StatsResponse {
+  siteCount: number;
+  toolCount: number;
+  trustedToolCount: number;
+  contributorCount: number;
+}

package/src/common.ts

@@ -0,0 +1,41 @@
+// Common primitives shared across all Sider tiers.
+
+/** ISO-8601 timestamp string. */
+export type IsoTimestamp = string;
+
+export type HttpMethod =
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "PATCH"
+  | "DELETE"
+  | "HEAD"
+  | "OPTIONS";
+
+/**
+ * Minimal JSON Schema representation. Sider stores inferred request/response
+ * shapes and tool input schemas as JSON Schema so they are portable to MCP.
+ */
+export interface JSONSchema {
+  type?:
+    | "object"
+    | "array"
+    | "string"
+    | "number"
+    | "integer"
+    | "boolean"
+    | "null";
+  properties?: Record<string, JSONSchema>;
+  items?: JSONSchema;
+  required?: string[];
+  enum?: unknown[];
+  const?: unknown;
+  description?: string;
+  format?: string;
+  [k: string]: unknown;
+}
+
+/** Standard success/error envelope returned by sider_api. */
+export type ApiResponse<T> =
+  | { success: true; data: T; timestamp: IsoTimestamp }
+  | { success: false; error: string; timestamp: IsoTimestamp };

package/src/index.ts

@@ -0,0 +1,13 @@
+// @sudobility/sider_types — shared domain types for Sider.
+//
+// Three tiers, one hard rule: a plaintext secret exists in exactly ONE of them.
+//   - GLOBAL  (registry.ts): shared across all users; placeholders only.
+//   - PRIVATE (runtime.ts):  per-user server data; uploaded already tokenized.
+//   - LOCAL   (local.ts):    browser only; the sole holder of real secret values.
+
+export * from "./common";
+export * from "./registry";
+export * from "./runtime";
+export * from "./local";
+export * from "./api";
+export * from "./actions";

package/src/local.ts

@@ -0,0 +1,29 @@
+// ============================================================================
+// LOCAL TIER — browser only.
+//
+// Nothing in this file is EVER uploaded to sider_api, written to a server
+// database, or placed in an LLM prompt. It lives in chrome.storage.session
+// (per-tab, cleared on close) and in memory.
+// ============================================================================
+
+import type { IsoTimestamp } from "./common";
+import type { ResolverHint } from "./registry";
+
+/**
+ * Maps a global SecretSlot to how its value is found in THIS user's session,
+ * and (transiently) to the value itself.
+ *
+ * `currentValue` is the ONLY field in the entire Sider type system that may
+ * hold a plaintext secret. It exists only in the tab that already legitimately
+ * holds the user's own credential, is read fresh at egress, and is never
+ * persisted to disk or transmitted anywhere.
+ */
+export interface TokenMapEntry {
+  /** Matches a global SecretSlot.id. */
+  slotId: string;
+  /** The hint that actually resolved a value in this session. */
+  resolver: ResolverHint;
+  /** Read fresh at egress; never persisted or transmitted. */
+  currentValue?: string;
+  lastSeenAt: IsoTimestamp;
+}

package/src/registry.ts

@@ -0,0 +1,258 @@
+// ============================================================================
+// GLOBAL TIER — the shared registry.
+//
+// Every type in this file is shared across ALL users of a site. It therefore
+// may NEVER contain a plaintext secret. Secrets appear only as placeholder
+// references to SecretSlot ids (e.g. "{key}" bound to { kind: "secret", slotId }).
+// The plaintext value of a secret lives exclusively in the browser (see
+// ./local.ts — TokenMapEntry).
+// ============================================================================
+
+import type { HttpMethod, IsoTimestamp, JSONSchema } from "./common";
+
+// ---------------------------------------------------------------------------
+// Site
+// ---------------------------------------------------------------------------
+
+export interface SitePolicy {
+  /** If true, Sider is disabled on this origin (denylist: banking/health/etc.). */
+  blocked: boolean;
+  /** Whether the assistant may perform write/financial actions on this site. */
+  allowMutations: boolean;
+  /** Rate cap applied to Sider-issued requests on this origin. */
+  maxRequestsPerMinute: number;
+}
+
+export interface Site {
+  id: string;
+  /** Scheme + host (+ port). The trust/same-origin boundary. */
+  origin: string;
+  name: string;
+  policy: SitePolicy;
+  toolCount: number;
+  trustedToolCount: number;
+  contributorCount: number;
+  createdAt: IsoTimestamp;
+  updatedAt: IsoTimestamp;
+}
+
+// ---------------------------------------------------------------------------
+// Endpoint templates
+// ---------------------------------------------------------------------------
+
+export type EndpointCategory =
+  | "read"
+  | "write"
+  | "auth"
+  | "telemetry"
+  | "unknown";
+
+export interface FieldSemantics {
+  /** JSON path within the request or response (e.g. "data.sections[].price"). */
+  jsonPath: string;
+  meaning: string;
+  type: string;
+  /** True if this field is an identifier (candidate for a data-flow edge). */
+  isId: boolean;
+  /** If this field feeds a param of another endpoint, the target template id. */
+  linksToTemplateId?: string;
+  isPII: boolean;
+  /** If true, this field is represented by a SecretSlot rather than a raw value. */
+  isSecret: boolean;
+}
+
+/** Which credentials an endpoint requires — described structurally, never by value. */
+export interface AuthProfile {
+  /** SecretSlot ids that must be resolved at call time. */
+  requiredSlotIds: string[];
+  /** Header names observed carrying auth (values are never recorded). */
+  authHeaderNames: string[];
+  /** Whether the endpoint relies on cookies the browser attaches automatically. */
+  usesCookies: boolean;
+}
+
+export interface EndpointTemplate {
+  id: string;
+  siteId: string;
+  method: HttpMethod;
+  /** Path with params extracted: "/api/sections/{sectionId}/seats". */
+  pathTemplate: string;
+  /** For GraphQL: the operation name (the URL alone is not distinguishing). */
+  graphqlOperation?: string;
+  description: string;
+  category: EndpointCategory;
+  requestSchema: JSONSchema;
+  responseSchema: JSONSchema;
+  requestFields: FieldSemantics[];
+  responseFields: FieldSemantics[];
+  authProfile: AuthProfile;
+  observationCount: number;
+  corroboratingUserCount: number;
+  confidence: number;
+  createdAt: IsoTimestamp;
+  updatedAt: IsoTimestamp;
+}
+
+// ---------------------------------------------------------------------------
+// Secret slots — the shareable DEFINITION of a secret (never its value).
+// ---------------------------------------------------------------------------
+
+export type SecretKind =
+  | "bearer"
+  | "csrf"
+  | "api_key"
+  | "session"
+  | "signature"
+  | "pii"
+  | "unknown";
+
+export type SecretRole =
+  // Browser attaches it automatically (credentials:'include'); the slot exists
+  // ONLY so samples get placeholder-ized. No substitution at execution.
+  | "auto_cookie"
+  // Must be resolved locally and substituted at egress (JS-set headers, CSRF,
+  // body fields, query params).
+  | "active_inject";
+
+/** WHERE a secret is allowed to be placed — enforced at egress (Gate B). */
+export type InjectionLocation =
+  | { at: "header"; name: string }
+  | { at: "query"; param: string }
+  | { at: "body"; jsonPath: string }
+  | { at: "cookie"; name: string };
+
+/**
+ * WHERE to find the current value of a secret in the user's own session.
+ * Carries structural identifiers (cookie NAME, storage KEY, selector) only —
+ * never the value itself. Each user's browser resolves its own value.
+ */
+export type ResolverHint =
+  | { from: "cookie"; name: string }
+  | { from: "storage"; area: "local" | "session"; key: string }
+  | { from: "dom"; selector: string; attr?: string }
+  | { from: "response"; endpointTemplateId: string; jsonPath: string };
+
+export interface SecretSlot {
+  /** Placeholder id used in recipes and tokenized samples, e.g. "site:<id>:auth_bearer". */
+  id: string;
+  siteId: string;
+  kind: SecretKind;
+  role: SecretRole;
+  injectionLocation: InjectionLocation;
+  /** Same-origin lock (Gate A): a recipe host must equal this origin to use the slot. */
+  allowedDestination: string;
+  /** Ranked structural hints for locating the current value locally. Never values. */
+  resolverHints: ResolverHint[];
+  confidence: number;
+  createdAt: IsoTimestamp;
+  updatedAt: IsoTimestamp;
+  // INVARIANT: there is deliberately NO `value` field, and never will be. A
+  // secret's plaintext exists only in the browser tab that already holds the
+  // user's own session (see ./local.ts — TokenMapEntry.currentValue).
+}
+
+// ---------------------------------------------------------------------------
+// Tools (MCP-shaped) + invocation recipes
+// ---------------------------------------------------------------------------
+
+export type SafetyClass = "read" | "write" | "financial";
+export type ToolStatus = "provisional" | "trusted" | "flagged";
+
+/** Resolves a single `{key}` placeholder used anywhere in a recipe. */
+export type ParamBinding =
+  | { kind: "literal"; value: string }
+  | { kind: "arg"; argName: string } // from the tool inputSchema / the user
+  | { kind: "secret"; slotId: string } // resolved LOCALLY at egress
+  | { kind: "priorOutput"; stepRef: string; jsonPath: string }; // graph edge, this run
+
+export interface HeaderTemplate {
+  name: string;
+  /** May contain `{key}` placeholders resolved via InvocationRecipe.bindings. */
+  valueTemplate: string;
+}
+
+export interface SignatureModel {
+  type: "none" | "hmac" | "unknown";
+  /** When type !== "none", the endpoint typically cannot be replayed via a
+   *  direct call and must be driven through DOM emulation instead. */
+  note?: string;
+}
+
+/** One sub-call of a composite/paginating tool. */
+export interface ComposeStep {
+  /** Referenced by later `{ kind: "priorOutput", stepRef }` bindings. */
+  ref: string;
+  toolId: string;
+  argBindings: Record<string, ParamBinding>;
+  /** If set, run once per element of the array at this jsonPath in the prior
+   *  result (fan-out) — e.g. "for each section, fetch its seats". */
+  forEachJsonPath?: string;
+}
+
+export interface InvocationRecipe {
+  method: HttpMethod;
+  /** Path/template relative to the site origin. Placeholders: `{key}`. */
+  urlTemplate: string;
+  headers: HeaderTemplate[];
+  /** JSON body template; string values may contain `{key}` placeholders. */
+  bodyTemplate?: unknown;
+  credentials: "include";
+  /** Resolves every `{key}` used in urlTemplate / headers / bodyTemplate. */
+  bindings: Record<string, ParamBinding>;
+  signatureModel?: SignatureModel;
+  /** For composite/paginating tools: ordered sub-calls that feed later bindings. */
+  compose?: ComposeStep[];
+}
+
+export interface ToolSpec {
+  id: string;
+  siteId: string;
+  name: string;
+  description: string;
+  /** Short imperative user-facing label ("Search for a product"); "" = none. */
+  capabilityLabel?: string;
+  inputSchema: JSONSchema;
+  safetyClass: SafetyClass;
+  /** false ⇒ signed/HMAC or otherwise non-replayable → DOM emulation only. */
+  directCallAvailable: boolean;
+  recipe: InvocationRecipe;
+  status: ToolStatus;
+  version: number;
+  observationCount: number;
+  /** Distinct users whose learned recipe corroborated this tool (trust gate). */
+  corroboratingUserCount: number;
+  confidence: number;
+  createdAt: IsoTimestamp;
+  updatedAt: IsoTimestamp;
+}
+
+// ---------------------------------------------------------------------------
+// Endpoint graph + UX recipes
+// ---------------------------------------------------------------------------
+
+export interface EndpointGraphEdge {
+  id: string;
+  siteId: string;
+  fromTemplateId: string;
+  /** Field in the source response that supplies the value. */
+  fromJsonPath: string;
+  toTemplateId: string;
+  /** Param of the target endpoint that the value feeds. */
+  toParam: string;
+  confidence: number;
+}
+
+export interface UXRecipe {
+  id: string;
+  siteId: string;
+  /** Natural-language goal pattern this recipe serves, e.g. "find cheapest seats". */
+  goalPattern: string;
+  /** Key of a generative-UI component the extension knows how to render. */
+  componentKey: string;
+  /** How to source the component's data. */
+  binding: {
+    toolId: string;
+    argBindings: Record<string, ParamBinding>;
+  };
+  status: ToolStatus;
+}

package/src/runtime.ts

@@ -0,0 +1,144 @@
+// ============================================================================
+// PRIVATE TIER (per-user server data) + browser-side execution helper types.
+//
+// Capture data reaches this tier already TOKENIZED — every secret value is a
+// placeholder before it ever leaves the browser. Plan/audit records store the
+// SHAPE of args and results, never secret values.
+// ============================================================================
+
+import type { HttpMethod, IsoTimestamp } from "./common";
+import type { SafetyClass } from "./registry";
+
+// ---------------------------------------------------------------------------
+// Capture (PRIVATE, tokenized before upload)
+// ---------------------------------------------------------------------------
+
+export interface RequestContext {
+  /** Page route when the request fired. */
+  route: string;
+  /** DOM element the user interacted with just before the request, if any. */
+  triggerSelector?: string;
+  pageTitle?: string;
+}
+
+/**
+ * A single observed request/response.
+ *
+ * TOKENIZED: every secret value is already a "{{slot:…}}" placeholder before
+ * this object leaves the browser. Auth header values are placeholders or were
+ * dropped entirely in the browser's redaction pre-pass.
+ */
+export interface Observation {
+  id: string;
+  batchId: string;
+  /** Assigned during clustering. */
+  endpointTemplateId?: string;
+  method: HttpMethod;
+  url: string;
+  requestHeaders: Record<string, string>;
+  requestBody?: unknown;
+  status: number;
+  responseBody?: unknown;
+  timingMs: number;
+  context: RequestContext;
+  createdAt: IsoTimestamp;
+}
+
+export type CaptureBatchStatus =
+  | "buffering"
+  | "uploaded"
+  | "distilled"
+  | "discarded";
+
+export interface CaptureBatch {
+  id: string;
+  contributorId: string;
+  siteId: string;
+  status: CaptureBatchStatus;
+  observationCount: number;
+  createdAt: IsoTimestamp;
+}
+
+// ---------------------------------------------------------------------------
+// Planning / execution (PRIVATE audit)
+// ---------------------------------------------------------------------------
+
+export type StepKind = "tool_call" | "dom_action" | "ask_user" | "done";
+
+export type StepStatus =
+  | "pending"
+  | "awaiting_confirm"
+  | "running"
+  | "done"
+  | "error"
+  | "aborted";
+
+export interface PlanStep {
+  id: string;
+  runId: string;
+  index: number;
+  kind: StepKind;
+  toolId?: string;
+  safetyClass?: SafetyClass;
+  /** Shape/keys of args only — never secret values. */
+  argsShape?: unknown;
+  status: StepStatus;
+  /** Shape of the result — never secret values. */
+  resultShape?: unknown;
+  rationale?: string;
+  error?: string;
+  startedAt?: IsoTimestamp;
+  finishedAt?: IsoTimestamp;
+}
+
+export type PlanRunStatus =
+  | "planning"
+  | "awaiting_approval"
+  | "running"
+  | "completed"
+  | "aborted"
+  | "error";
+
+export interface PlanRun {
+  id: string;
+  contributorId: string;
+  siteId: string;
+  goal: string;
+  status: PlanRunStatus;
+  createdAt: IsoTimestamp;
+  finishedAt?: IsoTimestamp;
+}
+
+export interface Contributor {
+  firebaseUid: string;
+  reputation: number;
+  createdAt: IsoTimestamp;
+}
+
+// ---------------------------------------------------------------------------
+// Execution engine (browser-side) helper types
+// ---------------------------------------------------------------------------
+
+/**
+ * Output of sider_lib compiling a ToolSpec + args, BEFORE detokenization.
+ * Placeholders are still present; secrets are substituted only after all three
+ * egress gates pass.
+ */
+export interface CompiledRequest {
+  method: HttpMethod;
+  url: string; // placeholders still present
+  headers: Record<string, string>;
+  body?: unknown;
+  credentials: "include";
+  referencedSlotIds: string[];
+  safetyClass: SafetyClass;
+}
+
+/** Result of an egress gate check (same-origin / injection-location / safety). */
+export type GateOutcome =
+  | { ok: true }
+  | {
+      ok: false;
+      gate: "same_origin" | "injection_location" | "safety";
+      reason: string;
+    };