@pinta-ai/pinta-copilot 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to pinta-copilot are documented here.
+
+## [0.1.0] - 2026-06-09
+
+Initial release. Forked from `pinta-cc` (Claude Code adapter); core layer
+(otlp/transport/retry-queue/redact/guard) reused. Verified against real
+GitHub Copilot CLI 1.0.49 + VS Code extension and a live Pinta Manager guard.
+See [`DESIGNDOC.md`](./DESIGNDOC.md) for the full design.
+
+### Added
+
+- **GitHub Copilot adapter** covering two surfaces from one hook file —
+  Copilot CLI and the VS Code extension (in-editor Copilot Chat). A single
+  `~/.copilot/hooks/pinta-copilot.json` fires on both; **no VS Code setting
+  required** (`chat.useClaudeHooks` default `false` works).
+- **3-way event discriminator + env fallback** — resolves the hook name from
+  `hook_event_name` / `hookEventName` / `hookName`, then `PINTA_COPILOT_EVENT`
+  (CLI `permissionRequest` uses a camelCase `hookName` schema; CLI
+  `subagentStart` ships no event-name field at all, so `install-hooks` stamps
+  the event name into each hook entry's `env`).
+- **Internal tools are telemetry-only** — `report_intent` / `ask_user` are
+  never guarded (denying them would brick the turn); `PINTA_GUARD_TIMEOUT_MS`
+  makes the guard client timeout configurable (default 50ms).
+- **`doctor`** — read-only health check (hook file, env, endpoint, surface).
+- **`DESIGNDOC.md`** — the as-built design document.
+- **Surface detection** (`copilot.surface` = `cli` | `ext` | `cloud`) via
+  `ELECTRON_RUN_AS_NODE` / `VSCODE_*` / `COPILOT_AGENT_*` — deliberately not
+  `TERM_PROGRAM` (integrated-terminal CLI would misclassify).
+- **Dual guard path** — `preToolUse` (all surfaces) + `permissionRequest`
+  (CLI only); deny is emitted in each event's expected format with reason.
+- **Always exit 0** — Copilot CLI `preToolUse` is fail-closed, so adapter
+  crashes must never block tools / brick the agent.
+- **Bronze flattening** into `copilot.*`, `ingest.type="copilot"`; both CLI and
+  ext payload shapes pass through losslessly.
+- **Config via env file** `~/.copilot/pinta-copilot.env` (unset-only load).
+- **Per-turn ULID trace keyed by `session_id`** (concurrent CLI + ext safe).
+- `tools/install-hooks` — writes/removes the user-level hook file with absolute
+  paths.
+
+### Changed from pinta-cc
+
+- Span prefix `cc.*` → `copilot.*`; `ingest.type` `cc` → `copilot`;
+  `service.name` `claude-code` → `copilot`.
+- Plugin/marketplace channel removed (direct hook-file install only).
+- Handlers consolidated into `index.ts`; config data dir anchored at
+  `~/.copilot/pinta-copilot-data` (cwd-independent).
+
+### Removed (pinta-cc / Claude residue)
+
+- `env-bridge.ts` (`CLAUDE_PLUGIN_OPTION_*` → OTel bridge) — plugin-channel only,
+  unused for direct install. Config now comes from the env file via
+  **namespaced vars** `COPILOT_PLUGIN_OPTION_ENDPOINT` / `COPILOT_PLUGIN_OPTION_HEADERS`
+  (so they don't collide with Copilot's native OTel `OTEL_EXPORTER_OTLP_*`, which
+  remain a lower-priority fallback); the guard relay token is `PINTA_RELAY_TOKEN`.
+- Dead `hasOtlpEndpoint()`, the `CLAUDE_PLUGIN_DATA` fallback, the unused
+  `identity.ts` stub, and stale `[pinta-cc]` log branding / Claude-referencing
+  comments.

package/LICENSE

@@ -0,0 +1,136 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to
+distribute copies of the software.  Your license to distribute
+covers distributing the software with changes and new works
+permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Pinta AI (https://pinta.sh)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make
+changes and new works based on the software for any permitted
+purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization, or
+government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law.  These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control
+of, or are under common control with that organization.
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+---
+
+Required Notice: Copyright (c) 2026 Pinta AI

package/README.md

@@ -0,0 +1,116 @@
+# pinta-copilot — OTLP forwarder + guard for GitHub Copilot hooks
+
+Converts **GitHub Copilot** hook events into OTLP/HTTP spans and forwards them to any OpenTelemetry-compatible collector, with an optional external **guard** that can allow/deny tool calls. Vendor-neutral. No Pinta CLI dependency. Identity is attached at the relay layer.
+
+A **single adapter + a single hook file** covers two surfaces:
+
+| Surface | Hook source | Guard | Notes |
+|---|---|---|---|
+| **Copilot CLI** | `~/.copilot/hooks/pinta-copilot.json` | `preToolUse` **+** `permissionRequest` | `preToolUse` is **fail-closed** |
+| **VS Code extension** (in-editor Copilot Chat) | same `~/.copilot/hooks/` file | `preToolUse` | `preToolUse` is fail-open |
+
+> Cloud agent (`.github/hooks/`) is out of scope for now.
+
+## Why it works with no VS Code setup
+
+The VS Code Copilot extension reads the **same** `~/.copilot/hooks/` file the CLI does (VS Code core `DEFAULT_HOOK_FILE_PATHS`). **No VS Code setting is required** — in particular `chat.useClaudeHooks` works at its default `false`. Install the one file and both the CLI and in-editor Copilot Chat fire it. (Verified against Copilot CLI 1.0.49 + VS Code, 2026-06.)
+
+## ⚠️ Fail-closed safety
+
+Copilot's **CLI `preToolUse` hook is fail-closed**: a non-zero exit, crash, or timeout *denies* the tool — and a crashing hook blocks `report_intent`/`ask_user` too, bricking the whole agent turn. This adapter therefore **always exits 0** on every path; transport and guard failures are absorbed (telemetry fail-open). Do not patch in code paths that can throw past the top-level handler.
+
+## Install
+
+```bash
+git clone https://github.com/pinta-ai/pinta-copilot.git
+cd pinta-copilot
+npm install && npm run build
+npm run install-hooks        # writes ~/.copilot/hooks/pinta-copilot.json (absolute paths)
+```
+
+Restart the Copilot CLI / reload the VS Code window to load hooks. Remove with `npm run uninstall-hooks`.
+
+> Managed installs (Pinta Manager) write the same file via the sidecar enroll module — no manual step.
+
+## Configuration
+
+Config is read from an **env file** the adapter loads at startup — `~/.copilot/pinta-copilot.env` (or `$COPILOT_HOME/pinta-copilot.env`), `KEY=VALUE` per line. Explicit `process.env` (incl. a hook `env` block) overrides the file; the file overrides legacy keys.
+
+```env
+# ~/.copilot/pinta-copilot.env
+COPILOT_PLUGIN_OPTION_ENDPOINT=https://your-collector.example.com/v1/traces
+COPILOT_PLUGIN_OPTION_HEADERS=x-pinta-relay-token=YOUR-TOKEN
+# optional: external guard (allow/deny tool calls)
+PINTA_GUARD_ENDPOINT=https://your-relay.example.com/guard
+```
+
+| Var | Purpose |
+|---|---|
+| `COPILOT_PLUGIN_OPTION_ENDPOINT` | Full OTLP/HTTP traces URL. **Namespaced to avoid colliding with Copilot's native OTel** (`OTEL_EXPORTER_OTLP_*`). The standard `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_ENDPOINT` are honored as a lower-priority fallback. |
+| `COPILOT_PLUGIN_OPTION_HEADERS` | `key=val,key=val` request headers (auth). Falls back to `OTEL_EXPORTER_OTLP_HEADERS`. |
+| `PINTA_GUARD_ENDPOINT` | Optional. POST'd on `preToolUse`/`permissionRequest`; a `DENY` response blocks the tool. |
+| `COPILOT_HOME` | Overrides `~/.copilot` for hook + env-file paths. |
+
+## Guard (allow / deny + reason)
+
+On `preToolUse` (all surfaces) and `permissionRequest` (CLI only) the adapter queries `PINTA_GUARD_ENDPOINT`. A `DENY` is emitted in the surface-appropriate format and the reason is shown to the model/user:
+
+- `preToolUse` → `{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "<reason>" } }`
+- `permissionRequest` → `{ "behavior": "deny", "message": "<reason>" }`
+
+Guard is **fail-open** (no endpoint / timeout / error → allow), so it never breaks a session.
+
+## Span conventions
+
+| Attribute | Value |
+|---|---|
+| `ingest.type` | `"copilot"` (aware-backend discriminator) |
+| `copilot.hook` | Hook event name (resolved from `hook_event_name` / `hookEventName` / `hookName`) |
+| `copilot.surface` | `cli` \| `ext` \| `cloud` (runtime-detected) |
+| `copilot.<key>` | Every other top-level field (Bronze flattening, raw key preserved) |
+| `service.name` | `"copilot"` · `telemetry.sdk.name` `"pinta-copilot"` |
+
+### CLI ↔ ext payload differences (absorbed by the adapter)
+
+| | CLI | ext |
+|---|---|---|
+| discriminator | `hook_event_name` (snake); `permissionRequest` uses `hookName` (camel) | `hook_event_name` (snake) |
+| tool result | `tool_result` (structured) | `tool_response` (Claude-style) |
+| `tool_use_id` | absent | present |
+| `transcript_path` | Stop only | every event |
+| subagent id | `agent_name`/`agent_display_name` | `agent_id`/`agent_type` |
+| `permissionRequest` | fires | not fired |
+
+Bronze flattening passes both shapes through losslessly; the backend's `CopilotIngestData` normalizes (`tool_response ?? tool_result`, `agent_id ?? agent_name`, …).
+
+## Architecture
+
+```
+src/
+├── index.ts              # stdin → classify → trace → guard → span → exit 0 (always)
+├── env-file.ts           # ~/.copilot/pinta-copilot.env loader (unset-only)
+├── core/
+│   ├── types.ts          # 3-way discriminator + snake/camel field absorption + classify
+│   ├── surface.ts        # cli | cloud | ext detection (ELECTRON_RUN_AS_NODE, …; NOT TERM_PROGRAM)
+│   ├── otlp.ts           # Bronze flattening (copilot.*) + ingest.type + surface + guard attrs
+│   ├── trace.ts          # per-turn ULID trace, keyed by session_id
+│   ├── transport.ts      # POST OTLP/HTTP traces (reads OTel env at call time)
+│   ├── retry-queue.ts    # file-backed JSONL queue, flushed next invocation
+│   ├── guard.ts          # POST PINTA_GUARD_ENDPOINT (50ms), fail-open
+│   ├── redact.ts         # Tier-1 redaction + Tier-3 truncation
+│   ├── config.ts / env-bridge.ts
+└── tools/install-hooks.ts  # write/remove ~/.copilot/hooks/pinta-copilot.json
+```
+
+## Development
+
+```bash
+npm install
+npm run build         # tsc → dist/
+npm test              # vitest
+npm run mock-server   # local OTLP collector
+```
+
+## License
+
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0) — see [LICENSE](LICENSE). Commercial use is not permitted; contact Pinta AI for a commercial license.

package/dist/core/config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Runtime config. Endpoint/headers come from OTEL_EXPORTER_OTLP_* env vars
+ * (loaded from ~/.copilot/pinta-copilot.env at startup) — not in this struct.
+ *
+ * pinta-copilot is installed as a direct hook file (D4), so the data dir
+ * (trace + retry-queue) must be a STABLE location independent of cwd —
+ * otherwise the per-turn trace written by UserPromptSubmit can't be read back
+ * by the following PreToolUse if cwd differs. We anchor it under the Copilot
+ * home (`$COPILOT_HOME` or `~/.copilot`).
+ */
+export interface PintaConfig {
+    pluginData: string;
+    tracePath: string;
+}
+export declare function loadConfig(): PintaConfig;

package/dist/core/config.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+function copilotHome() {
+    return process.env.COPILOT_HOME || path_1.default.join(os_1.default.homedir(), ".copilot");
+}
+function loadConfig() {
+    const pluginData = process.env.COPILOT_PLUGIN_DATA || path_1.default.join(copilotHome(), "pinta-copilot-data");
+    return {
+        pluginData,
+        tracePath: path_1.default.join(pluginData, "trace.json"),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":";;;;;AAsBA,gCAOC;AA7BD,4CAAoB;AACpB,gDAAwB;AAiBxB,SAAS,WAAW;IAClB,OAAO,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,cAAI,CAAC,IAAI,CAAC,YAAE,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;AACzE,CAAC;AAED,SAAgB,UAAU;IACxB,MAAM,UAAU,GACd,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,cAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,oBAAoB,CAAC,CAAC;IACpF,OAAO;QACL,UAAU;QACV,SAAS,EAAE,cAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC;KAC/C,CAAC;AACJ,CAAC"}

package/dist/core/env-bridge.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bridge Claude Code's userConfig env vars (CLAUDE_PLUGIN_OPTION_*) to the
+ * OTel SDK standard env vars (OTEL_EXPORTER_OTLP_*).
+ *
+ * Claude Code maps each plugin.json `userConfig.<key>` to a corresponding
+ * `CLAUDE_PLUGIN_OPTION_<KEY>` env var on hook spawn. We keep the user-
+ * facing names friendly (`endpoint`, `api_key`) and translate them into the
+ * canonical OTel env names so transport.ts (and any future OTel SDK adoption)
+ * can read them via the OTel-spec names.
+ *
+ * The user-facing `endpoint` is treated as a *full* OTLP/HTTP traces URL
+ * (e.g., `http://127.0.0.1:5147/v1/traces`), so we map it to
+ * `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (signal-specific full URL per OTel
+ * spec) rather than `OTEL_EXPORTER_OTLP_ENDPOINT` (which is a base URL the
+ * SDK appends `/v1/traces` to). This way both the OTel SDK (when used) and
+ * pinta-cc's hand-written transport agree on the URL without any path
+ * manipulation downstream.
+ *
+ * Pinta Manager auto-injects `CLAUDE_PLUGIN_OPTION_*` via Claude Code's
+ * settings.json. OSS users fill them in via the `/plugin install` UI.
+ *
+ * Existing OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / HEADERS take precedence
+ * (explicit override).
+ */
+export declare function bridgeUserConfigToOtelEnv(): void;

package/dist/core/env-bridge.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bridgeUserConfigToOtelEnv = bridgeUserConfigToOtelEnv;
+/**
+ * Bridge Claude Code's userConfig env vars (CLAUDE_PLUGIN_OPTION_*) to the
+ * OTel SDK standard env vars (OTEL_EXPORTER_OTLP_*).
+ *
+ * Claude Code maps each plugin.json `userConfig.<key>` to a corresponding
+ * `CLAUDE_PLUGIN_OPTION_<KEY>` env var on hook spawn. We keep the user-
+ * facing names friendly (`endpoint`, `api_key`) and translate them into the
+ * canonical OTel env names so transport.ts (and any future OTel SDK adoption)
+ * can read them via the OTel-spec names.
+ *
+ * The user-facing `endpoint` is treated as a *full* OTLP/HTTP traces URL
+ * (e.g., `http://127.0.0.1:5147/v1/traces`), so we map it to
+ * `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (signal-specific full URL per OTel
+ * spec) rather than `OTEL_EXPORTER_OTLP_ENDPOINT` (which is a base URL the
+ * SDK appends `/v1/traces` to). This way both the OTel SDK (when used) and
+ * pinta-cc's hand-written transport agree on the URL without any path
+ * manipulation downstream.
+ *
+ * Pinta Manager auto-injects `CLAUDE_PLUGIN_OPTION_*` via Claude Code's
+ * settings.json. OSS users fill them in via the `/plugin install` UI.
+ *
+ * Existing OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / HEADERS take precedence
+ * (explicit override).
+ */
+function bridgeUserConfigToOtelEnv() {
+    if (process.env.CLAUDE_PLUGIN_OPTION_ENDPOINT &&
+        !process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) {
+        process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT =
+            process.env.CLAUDE_PLUGIN_OPTION_ENDPOINT;
+    }
+    if (process.env.CLAUDE_PLUGIN_OPTION_API_KEY && !process.env.OTEL_EXPORTER_OTLP_HEADERS) {
+        process.env.OTEL_EXPORTER_OTLP_HEADERS =
+            `x-pinta-relay-token=${process.env.CLAUDE_PLUGIN_OPTION_API_KEY}`;
+    }
+    // Expose for guard.ts (~/guard/evaluate auth header)
+    if (!process.env.PINTA_RELAY_TOKEN && process.env.CLAUDE_PLUGIN_OPTION_API_KEY) {
+        process.env.PINTA_RELAY_TOKEN = process.env.CLAUDE_PLUGIN_OPTION_API_KEY;
+    }
+}
+//# sourceMappingURL=env-bridge.js.map

package/dist/core/env-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-bridge.js","sourceRoot":"","sources":["../../src/core/env-bridge.ts"],"names":[],"mappings":";;AAwBA,8DAgBC;AAxCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,yBAAyB;IACvC,IACE,OAAO,CAAC,GAAG,CAAC,6BAA6B;QACzC,CAAC,OAAO,CAAC,GAAG,CAAC,kCAAkC,EAC/C,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,kCAAkC;YAC5C,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,CAAC;QACxF,OAAO,CAAC,GAAG,CAAC,0BAA0B;YACpC,uBAAuB,OAAO,CAAC,GAAG,CAAC,4BAA4B,EAAE,CAAC;IACtE,CAAC;IACD,qDAAqD;IACrD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC,4BAA4B,EAAE,CAAC;QAC/E,OAAO,CAAC,GAAG,CAAC,iBAAiB,GAAG,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC;IAC3E,CAAC;AACH,CAAC"}

package/dist/core/guard.d.ts

@@ -0,0 +1,14 @@
+export interface GuardInput {
+    spanId: string;
+    toolName?: string;
+    toolInput?: unknown;
+    rawTextFields?: Record<string, string>;
+}
+export interface GuardResult {
+    decision: 'ALLOW' | 'DENY' | 'REVIEW';
+    reason: string | null;
+    userMessage: string | null;
+    durationMs: number;
+    failOpenReason?: 'timeout' | 'refused' | 'error';
+}
+export declare function evaluateGuard(input: GuardInput, endpoint: string | undefined): Promise<GuardResult | null>;

package/dist/core/guard.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateGuard = evaluateGuard;
+// Guard must be fast or fail-open. 50ms default keeps the hook snappy;
+// override for slower relays (or test harnesses) via PINTA_GUARD_TIMEOUT_MS.
+const TIMEOUT_MS = Number(process.env.PINTA_GUARD_TIMEOUT_MS) || 50;
+function sleep(ms) {
+    return new Promise((_, reject) => setTimeout(() => {
+        const err = new Error('Guard request timed out');
+        err.name = 'TimeoutError';
+        reject(err);
+    }, ms));
+}
+async function evaluateGuard(input, endpoint) {
+    if (!endpoint)
+        return null;
+    if (process.env.PINTA_GUARD_DISABLED === '1')
+        return null;
+    const start = Date.now();
+    try {
+        const res = await Promise.race([
+            fetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-pinta-relay-token': process.env.PINTA_RELAY_TOKEN ?? '',
+                },
+                body: JSON.stringify({ input }),
+            }),
+            sleep(TIMEOUT_MS),
+        ]);
+        if (res.status !== 200) {
+            return { decision: 'ALLOW', reason: null, userMessage: null, durationMs: Date.now() - start, failOpenReason: 'error' };
+        }
+        const body = (await res.json());
+        return {
+            decision: body.decision,
+            reason: body.reason,
+            userMessage: body.userMessage ?? null,
+            durationMs: body.durationMs ?? (Date.now() - start),
+        };
+    }
+    catch (err) {
+        const reason = err.name === 'TimeoutError' ? 'timeout' : 'error';
+        return { decision: 'ALLOW', reason: null, userMessage: null, durationMs: Date.now() - start, failOpenReason: reason };
+    }
+}
+//# sourceMappingURL=guard.js.map

package/dist/core/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../src/core/guard.ts"],"names":[],"mappings":";;AAgCA,sCAsCC;AApDD,uEAAuE;AACvE,6EAA6E;AAC7E,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,IAAI,EAAE,CAAC;AAEpE,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC/B,UAAU,CAAC,GAAG,EAAE;QACd,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QACjD,GAAG,CAAC,IAAI,GAAG,cAAc,CAAC;QAC1B,MAAM,CAAC,GAAG,CAAC,CAAC;IACd,CAAC,EAAE,EAAE,CAAC,CACP,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,aAAa,CACjC,KAAiB,EACjB,QAA4B;IAE5B,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YAC7B,KAAK,CAAC,QAAQ,EAAE;gBACd,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,qBAAqB,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,EAAE;iBAC3D;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC;aAChC,CAAC;YACF,KAAK,CAAC,UAAU,CAAC;SAClB,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC;QACzH,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAK7B,CAAC;QACF,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI;YACrC,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;SACpD,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAmC,GAAa,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;QAC3G,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;IACxH,CAAC;AACH,CAAC"}

package/dist/core/otlp.d.ts

@@ -0,0 +1,55 @@
+import type { GuardResult } from "./guard.js";
+import { type RawEvent } from "./types.js";
+import type { Surface } from "./surface.js";
+export interface OtlpAttribute {
+    key: string;
+    value: {
+        stringValue: string;
+    } | {
+        intValue: number;
+    } | {
+        doubleValue: number;
+    } | {
+        boolValue: boolean;
+    };
+}
+export interface OtlpSpan {
+    traceId: string;
+    spanId: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OtlpAttribute[];
+}
+export interface ResourceSpans {
+    resource: {
+        attributes: OtlpAttribute[];
+    };
+    scopeSpans: Array<{
+        scope: {
+            name: string;
+            version: string;
+        };
+        spans: OtlpSpan[];
+    }>;
+}
+export interface OtlpPayload {
+    resourceSpans: ResourceSpans[];
+}
+/**
+ * Convert a 26-char Crockford ULID into 32 lowercase hex chars (16 bytes)
+ * suitable for an OTLP traceId.
+ */
+export declare function ulidToTraceId(ulid: string): string;
+/** Generate a fresh 16-hex-char (8-byte) span ID. */
+export declare function newSpanId(): string;
+export declare function buildOtlpPayload(args: {
+    event: RawEvent;
+    traceId: string;
+    surface: Surface;
+    now?: number;
+    guard?: GuardResult | null;
+}): OtlpPayload;
+/** Concatenate per-hook payloads' resourceSpans into one OTLP payload. */
+export declare function mergeBatch(payloads: OtlpPayload[]): OtlpPayload;