@app-vitals/agent-lib 0.2.1 → 0.4.0

package/admin-types.ts

@@ -145,7 +145,9 @@ export interface paths {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["ProvisionAgentResult"] | components["schemas"]["ProvisionSkippedResult"];
+                        "application/json":
+                            | components["schemas"]["ProvisionAgentResult"]
+                            | components["schemas"]["ProvisionSkippedResult"];
                     };
                 };
                 /** @description Forbidden */
@@ -1432,6 +1434,134 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/agents/{id}/crons/{cronId}/runs/{runId}/transcript": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get a cron run transcript
+         * @description Returns the stored redacted transcript. `*`, `platform.read` and `platform.ops` callers only: an agent key is 403 even for its own runs. Every read writes an AgentTranscriptRead audit row before the response. 404 when SHIPWRIGHT_TRANSCRIPT_API_ENABLED is not `enabled` or no transcript exists.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    id: string;
+                    cronId: string;
+                    runId: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description The transcript */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CronRunTranscript"];
+                    };
+                };
+                /** @description Forbidden */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description No transcript, or transcript API disabled */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+            };
+        };
+        /**
+         * Upload a cron run transcript
+         * @description Stores (upserts) the runtime's already-redacted session transcript for a cron run, then keeps only the agent's newest 200 transcripts. Callers: the agent's own key, or `*`. `body` over 1 MiB (UTF-8 bytes) is a 413. 404 unless SHIPWRIGHT_TRANSCRIPT_API_ENABLED is `enabled`, or when the run is not owned by the cron/agent.
+         */
+        put: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    id: string;
+                    cronId: string;
+                    runId: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["UploadCronRunTranscriptBody"];
+                };
+            };
+            responses: {
+                /** @description Transcript stored */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CronRunTranscriptUploadResult"];
+                    };
+                };
+                /** @description Bad request */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Caller not allowed */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Run not found, or transcript API disabled */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Transcript body over 1 MiB */
+                413: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+            };
+        };
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/agents/{id}/plugins": {
         parameters: {
             query?: never;
@@ -1653,7 +1783,13 @@ export interface paths {
                 header?: never;
                 path: {
                     id: string;
-                    phase: "prd" | "plan-session" | "review" | "patch" | "deploy" | "dev-task";
+                    phase:
+                        | "prd"
+                        | "plan-session"
+                        | "review"
+                        | "patch"
+                        | "deploy"
+                        | "dev-task";
                 };
                 cookie?: never;
             };
@@ -2743,6 +2879,84 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/agents/{id}/crons/{cronId}/run-now": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Request an immediate run of a cron job
+         * @description Asks the agent's runtime to run the cron job once, now, with the job's own stored prompt. Takes no request body (any body is 400). Stamps `runRequestedAt` on the job and writes an AgentCronRunRequest audit row before returning 202; the runtime honours a fresh request (under 15 minutes old) once on its next cron sync. Callers: `*`, `platform.ops`, or the agent's own key. 404 unless SHIPWRIGHT_CRON_RUN_NOW_ENABLED is `enabled`; 409 when the trial-expiry lockdown disabled the cron.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    id: string;
+                    cronId: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Run requested */
+                202: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CronRunNowResponse"];
+                    };
+                };
+                /** @description A request body was sent */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Caller not allowed */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Cron not found, or cron run-now disabled */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Cron disabled by lockdown */
+                409: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/agents/{id}/ask": {
         parameters: {
             query?: never;
@@ -3131,6 +3345,13 @@ export interface components {
         CronWrapper: {
             cron: components["schemas"]["AgentCronJob"];
         };
+        CronRunNowResponse: {
+            /**
+             * Format: date-time
+             * @example 2026-10-26T12:00:00.000Z
+             */
+            requestedAt: string;
+        };
         AgentCronJob: {
             /** @example clx1234567890 */
             id: string;
@@ -3156,6 +3377,12 @@ export interface components {
             system: boolean;
             /** @example null */
             parentCronId: string | null;
+            /**
+             * Format: date-time
+             * @description Set by POST .../run-now; the runtime honours it once while fresh (15 minutes) and run creation with commandVariant run-now clears it.
+             * @example null
+             */
+            runRequestedAt: string | null;
             /**
              * Format: date-time
              * @example 2026-01-01T00:00:00.000Z
@@ -3565,6 +3792,53 @@ export interface components {
         TokensWrapper: {
             tokens: components["schemas"]["AgentToken"][];
         };
+        CronRunTranscriptUploadResult: {
+            /** @example clx1111111111 */
+            runId: string;
+            /** @example 2048 */
+            bytes: number;
+            /** @example false */
+            truncated: boolean;
+            /** @example 0 */
+            redactions: number;
+        };
+        UploadCronRunTranscriptBody: {
+            /**
+             * @description Claude session id the transcript was read from.
+             * @example 7c1c8d1e-0000-4000-8000-000000000000
+             */
+            sessionId?: string;
+            /** @description The already-redacted transcript (JSONL text). Over 1 MiB (UTF-8 bytes) is a 413. Never logged. */
+            body: string;
+            /**
+             * @description True when the runtime dropped earlier lines to fit.
+             * @example false
+             */
+            truncated: boolean;
+            /**
+             * @description How many secrets the runtime redacted.
+             * @example 0
+             */
+            redactions: number;
+        };
+        CronRunTranscript: {
+            /** @example clx1111111111 */
+            runId: string;
+            /** @example clx0987654321 */
+            cronId: string;
+            /** @example null */
+            sessionId: string | null;
+            /** @example 2048 */
+            bytes: number;
+            /** @example false */
+            truncated: boolean;
+            /** @example 0 */
+            redactions: number;
+            /** @example 2026-10-26T12:00:00.000Z */
+            createdAt: string;
+            /** @description Redacted JSONL transcript. */
+            body: string;
+        };
         PluginWrapper: {
             plugin: components["schemas"]["AgentPlugin"];
         };
@@ -3615,7 +3889,13 @@ export interface components {
              * @example review
              * @enum {string}
              */
-            phase: "prd" | "plan-session" | "review" | "patch" | "deploy" | "dev-task";
+            phase:
+                | "prd"
+                | "plan-session"
+                | "review"
+                | "patch"
+                | "deploy"
+                | "dev-task";
             /** @example shipwright:code-reviewer */
             subagentType: string | null;
             /**
@@ -3968,6 +4248,7 @@ export interface components {
             phaseMethodology: {
                 [key: string]: string | null;
             };
+            features?: components["schemas"]["AgentConfigFeatures"];
         };
         AgentConfigPlugin: {
             /** @example shipwright */
@@ -3975,6 +4256,18 @@ export interface components {
             /** @example shipwright */
             plugin: string;
         };
+        AgentConfigFeatures: {
+            /**
+             * @description True when SHIPWRIGHT_TRANSCRIPT_API_ENABLED is on: the runtime uploads a redacted transcript after each cron run.
+             * @example false
+             */
+            transcriptUpload: boolean;
+            /**
+             * @description Reserved for the repo-access check (COS-44.1).
+             * @example false
+             */
+            repoAccessCheck: boolean;
+        };
         RuntimeError: {
             /** @example Not found */
             error: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-lib",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/app-vitals/agent.git",
@@ -26,6 +26,7 @@
     "./pool-observability": "./pool-observability.ts",
     "./pricing": "./pricing.ts",
     "./progress-phases": "./progress-phases.ts",
+    "./redact": "./redact.ts",
     "./request-context": "./request-context.ts",
     "./secret-env-vars": "./secret-env-vars.ts",
     "./default-account": "./default-account.ts",

package/redact.ts

@@ -0,0 +1,70 @@
+/**
+ * lib/redact.ts
+ * Secret redaction for cron-run transcripts (COS-43.1). Lives in lib/ so the
+ * runtime (which redacts before upload) and admin can both import it.
+ *
+ * Two passes, both returning the redacted text plus how many substitutions
+ * were made:
+ *   - redactValues: the live values of SECRET_ENV_VARS (the same scrub the
+ *     Sentry hooks use, lib/sentry.ts redactSecrets).
+ *   - redactShapes: well-known credential shapes (GitHub/Anthropic/OpenAI/
+ *     Slack/AWS tokens, PEM private keys, bearer tokens, JWTs).
+ */
+
+import { liveSecretValues, redactSecrets } from "./sentry.ts";
+
+export interface RedactResult {
+  text: string;
+  count: number;
+}
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+export const REDACTED = "[REDACTED]";
+
+const SHAPES: readonly RegExp[] = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /github_pat_[A-Za-z0-9_]{20,}/g,
+  /ghp_[A-Za-z0-9]{20,}/g,
+  /sk-ant-[A-Za-z0-9_-]{20,}/g,
+  // Not preceded by an alphanumeric, so "task-<slug>" is not an OpenAI key.
+  /(?<![A-Za-z0-9])sk-[A-Za-z0-9]{20,}/g,
+  /xox[abprs]-[A-Za-z0-9-]{10,}/g,
+  /AKIA[A-Z0-9]{16}/g,
+  /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
+  /Bearer [A-Za-z0-9._-]{16,}/g,
+];
+
+/** Replaces the live values of SECRET_ENV_VARS in `env` (default process.env). */
+export function redactValues(
+  text: string,
+  env: Env = process.env,
+): RedactResult {
+  const secrets = liveSecretValues(env);
+  let count = 0;
+  for (const secret of secrets) {
+    count += text.split(secret).length - 1;
+  }
+  if (count === 0) return { text, count: 0 };
+  return { text: redactSecrets(text, secrets, new WeakSet(), 0), count };
+}
+
+/** Replaces well-known credential shapes. */
+export function redactShapes(text: string): RedactResult {
+  let count = 0;
+  let out = text;
+  for (const re of SHAPES) {
+    out = out.replace(re, () => {
+      count++;
+      return REDACTED;
+    });
+  }
+  return { text: out, count };
+}
+
+/** redactValues then redactShapes; counts are summed. */
+export function redact(text: string, env: Env = process.env): RedactResult {
+  const values = redactValues(text, env);
+  const shapes = redactShapes(values.text);
+  return { text: shapes.text, count: values.count + shapes.count };
+}

package/redact.unit.test.ts

@@ -0,0 +1,87 @@
+/**
+ * lib/redact.unit.test.ts
+ * Transcript redaction (COS-43.1): live secret values + token shapes.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { redact, redactShapes, redactValues } from "./redact.ts";
+
+const PLANTED: Record<string, string> = {
+  "GitHub classic PAT": `ghp_${"A1b2C3d4E5".repeat(3)}`,
+  "GitHub fine-grained PAT": `github_pat_${"a1B2c3D4_".repeat(4)}`,
+  "Anthropic key": `sk-ant-api03-${"Zy9-x8_W7".repeat(4)}`,
+  "OpenAI-style key": `sk-${"Qw3Er4Ty5U".repeat(3)}`,
+  "Slack token": "xoxb-1234567890-abcdefghij",
+  "AWS access key": "AKIAIOSFODNN7EXAMPLE",
+  "PEM private key": [
+    "-----BEGIN RSA PRIVATE KEY-----",
+    "MIIEowIBAAKCAQEAxyz",
+    "abcdef==",
+    "-----END RSA PRIVATE KEY-----",
+  ].join("\n"),
+  "Bearer token": "Bearer abcdefghijklmnop1234.-_",
+  JWT: "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dBjftJeZ4CVPmB92K27uhbUJU1p1r",
+};
+
+describe("redactShapes", () => {
+  for (const [name, token] of Object.entries(PLANTED)) {
+    it(`redacts a ${name} and counts it`, () => {
+      const out = redactShapes(`before ${token} after`);
+      expect(out.text).not.toContain(token);
+      expect(out.text).toContain("before ");
+      expect(out.text).toContain(" after");
+      expect(out.count).toBe(1);
+    });
+  }
+
+  it("redacts the PEM body, not just the header", () => {
+    const out = redactShapes(PLANTED["PEM private key"] as string);
+    expect(out.text).not.toContain("MIIEowIBAAKCAQEAxyz");
+    expect(out.text).not.toContain("END RSA PRIVATE KEY");
+  });
+
+  it("counts every occurrence", () => {
+    const t = PLANTED["GitHub classic PAT"] as string;
+    const out = redactShapes(`${t} and ${t}\n${PLANTED["AWS access key"]}`);
+    expect(out.count).toBe(3);
+    expect(out.text).not.toContain(t);
+  });
+
+  it("does not flag a sha256 hex digest or ordinary prose", () => {
+    const sha = `${"a".repeat(8)}${"0123456789abcdef".repeat(3)}deadbeef`;
+    const text = `commit ${sha} skipped the task-store; sk-short is fine`;
+    const out = redactShapes(text);
+    expect(out.text).toBe(text);
+    expect(out.count).toBe(0);
+  });
+});
+
+describe("redactValues", () => {
+  it("replaces live SECRET_ENV_VARS values and counts them", () => {
+    const env = { GH_TOKEN: "super-secret-gh-value", PATH: "/usr/bin" };
+    const out = redactValues(
+      "token=super-secret-gh-value again super-secret-gh-value /usr/bin",
+      env,
+    );
+    expect(out.text).not.toContain("super-secret-gh-value");
+    expect(out.text).toContain("/usr/bin");
+    expect(out.count).toBe(2);
+  });
+
+  it("is a no-op with no live secrets", () => {
+    expect(redactValues("hello", {})).toEqual({ text: "hello", count: 0 });
+  });
+});
+
+describe("redact", () => {
+  it("applies values then shapes and sums the counts", () => {
+    const env = { SLACK_BOT_TOKEN: "plain-live-value-123" };
+    const out = redact(
+      `a plain-live-value-123 b ${PLANTED["GitHub classic PAT"]}`,
+      env,
+    );
+    expect(out.count).toBe(2);
+    expect(out.text).not.toContain("plain-live-value-123");
+    expect(out.text).not.toContain("ghp_");
+  });
+});

package/sentry.ts

@@ -69,13 +69,15 @@ export interface ErrorCapturingClient {
 const MAX_SCRUB_DEPTH = 20;
 
 /** Recomputed per call (not cached at module load) so tests can mutate env freely between assertions. */
-function liveSecretValues(): string[] {
-  return SECRET_ENV_VARS.map((key) => process.env[key]).filter(
+export function liveSecretValues(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): string[] {
+  return SECRET_ENV_VARS.map((key) => env[key]).filter(
     (value): value is string => !!value,
   );
 }
 
-function redactSecrets<T>(
+export function redactSecrets<T>(
   value: T,
   secrets: string[],
   seen: WeakSet<object>,