@hyperdrive.bot/paseo-protocol 0.3.53 → 0.3.54

package/dist/messages.js

@@ -835,6 +835,26 @@ export const SessionDigestLinkSchema = z.object({
     url: z.string(),
     label: z.string().optional(),
 });
+/**
+ * A credential row on the session context rail.
+ *
+ * `value` is ALWAYS safe to render: the daemon runs every incoming value
+ * through `normalizeSecretForStorage` (see session-secrets.ts), so a live-shaped
+ * token is masked before it is ever persisted, pushed, or cached. That is why
+ * the app can offer a reveal button at all -- it uncovers something that was
+ * already harmless, not something the view layer was trusted to hide.
+ */
+export const SessionSecretSchema = z.object({
+    /** What it is, e.g. "GITLAB_TOKEN", "staging db user". Unique per digest. */
+    label: z.string().min(1).max(80),
+    /** Safe-to-render value: a placeholder verbatim, or a mask like "••••7f3a". */
+    value: z.string().max(200),
+    /** True when `value` is a mask rather than the real string. */
+    masked: z.boolean(),
+    /** Provenance, e.g. "env:GITLAB_TOKEN" or ".env.local". Never a value. */
+    source: z.string().max(200).optional(),
+    discoveredAt: z.string().optional(),
+});
 /**
  * Session digest — structured, machine-readable per-session metadata so an
  * orchestrator can triage a fleet without replaying transcripts. See
@@ -848,6 +868,13 @@ export const SessionDigestSchema = z.object({
     nextStep: z.string().optional(),
     blockers: z.array(z.string()).optional(),
     links: z.array(SessionDigestLinkSchema).optional(),
+    /**
+     * Non-live credentials and connection hints a session needs at hand:
+     * which token it authenticates with, which test user, which host. Written
+     * by the context hook, masked at the daemon boundary. See
+     * docs/session-context-rail.md.
+     */
+    secrets: z.array(SessionSecretSchema).optional(),
     keyFiles: z.array(z.string()).optional(),
     summary: z.string().optional(),
     accomplishments: z.array(z.string()).optional(),
@@ -1052,6 +1079,94 @@ export const BackgroundTaskOutputResponseSchema = z.object({
         requestId: z.string(),
     }),
 });
+/**
+ * What the daemon could find out about one external reference (a GitLab
+ * pipeline, a merge request, a GitHub PR, a Jira issue).
+ *
+ * Every field is nullable on purpose. Enrichment needs a provider credential
+ * the daemon may simply not have, and the honest answer to "what is this
+ * pipeline doing" is often "I cannot see it" -- which is what
+ * `unavailableReason` carries, so the card can say so instead of spinning.
+ */
+export const ReferenceEnrichmentSchema = z.object({
+    url: z.string(),
+    kind: z.string(),
+    /** Provider status verbatim: "running", "success", "In Review", "merged". */
+    status: z.string().nullable(),
+    /** A normalized bucket the UI colors on, so it never parses `status`. */
+    state: z.enum(["running", "success", "failed", "blocked", "neutral"]),
+    title: z.string().nullable(),
+    /** One supporting line: author, branch, assignee. */
+    detail: z.string().nullable(),
+    /** Countable progress where the provider has it, e.g. "12/14 jobs". */
+    progress: z.string().nullable(),
+    updatedAt: z.string().nullable(),
+    /** Set when nothing could be fetched. Null on success. */
+    unavailableReason: z.string().nullable(),
+    /** True while the underlying resource is still moving and worth re-polling. */
+    live: z.boolean(),
+});
+/**
+ * Ask the daemon to enrich reference URLs. On demand (like
+ * `list_background_tasks_request`), never on the snapshot hot path: the app
+ * polls this only while a context rail carrying live references is on screen.
+ *
+ * Credentials stay on the daemon. The app sends URLs and receives status.
+ */
+/**
+ * Record session context (external links + non-live credentials) onto an
+ * agent's digest from OUTSIDE the agent's own MCP session.
+ *
+ * This is the channel the context hook uses. `set_session_digest` is
+ * agent-scoped -- only the agent itself can call it -- but a Claude Code hook is
+ * a shell process beside the agent, not the agent, so it needs a door of its
+ * own. Merge semantics: links union by URL, secrets by label (later wins), and
+ * every secret is masked by the daemon before it is stored.
+ */
+export const SetAgentContextRequestMessageSchema = z.object({
+    type: z.literal("set_agent_context_request"),
+    agentId: z.string(),
+    links: z
+        .array(z.object({
+        kind: z.enum(["pr", "mr", "issue", "deploy", "preview", "doc", "other"]),
+        url: z.string().min(1).max(500),
+        label: z.string().max(80).optional(),
+    }))
+        .max(20)
+        .optional(),
+    secrets: z
+        .array(z.object({
+        label: z.string().min(1).max(80),
+        value: z.string().max(200),
+        source: z.string().max(200).optional(),
+    }))
+        .max(20)
+        .optional(),
+    requestId: z.string(),
+});
+export const SetAgentContextResponseSchema = z.object({
+    type: z.literal("set_agent_context_response"),
+    payload: z.object({
+        agentId: z.string(),
+        digest: SessionDigestSchema.nullable(),
+        /** How many secrets the daemon had to mask, so the hook can report it. */
+        maskedCount: z.number().int().nonnegative(),
+        error: z.string().optional(),
+        requestId: z.string(),
+    }),
+});
+export const EnrichReferencesRequestMessageSchema = z.object({
+    type: z.literal("enrich_references_request"),
+    urls: z.array(z.string().min(1).max(500)).max(20),
+    requestId: z.string(),
+});
+export const EnrichReferencesResponseSchema = z.object({
+    type: z.literal("enrich_references_response"),
+    payload: z.object({
+        enrichments: z.array(ReferenceEnrichmentSchema),
+        requestId: z.string(),
+    }),
+});
 export const DismissBackgroundTaskRequestMessageSchema = z.object({
     type: z.literal("dismiss_background_task_request"),
     agentId: z.string(),
@@ -2604,6 +2719,8 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
     DismissBackgroundTaskRequestMessageSchema,
     ListBackgroundTasksRequestMessageSchema,
     BackgroundTaskOutputRequestMessageSchema,
+    EnrichReferencesRequestMessageSchema,
+    SetAgentContextRequestMessageSchema,
     CloseItemsRequestMessageSchema,
     UpdateAgentRequestMessageSchema,
     ProjectRenameRequestSchema,
@@ -4796,6 +4913,8 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
     BackgroundTaskDismissedMessageSchema,
     ListBackgroundTasksResponseSchema,
     BackgroundTaskOutputResponseSchema,
+    EnrichReferencesResponseSchema,
+    SetAgentContextResponseSchema,
     CloseItemsResponseSchema,
     CheckoutStatusResponseSchema,
     CheckoutStatusUpdateSchema,

package/dist/session-references.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Session references -- turning a bare URL sitting in a session's digest into
+ * something the UI can render as a card instead of a link.
+ *
+ * The split matters. Classification is **pure and local**: given a URL string,
+ * decide what it is and pull the ids out of the path. Enrichment (is that
+ * pipeline green? what is that ticket called?) needs credentials and a network
+ * hop, so it lives on the daemon (`enrich_reference_request`) and never here.
+ *
+ * That split is the whole reason the app can show a useful reference card for a
+ * GitLab pipeline the instant the URL lands, and fill in "running / 12 of 14
+ * jobs" a moment later, without ever holding a provider token itself.
+ */
+export type SessionReferenceKind = "gitlab-pipeline" | "gitlab-merge-request" | "github-pull-request" | "jira-issue" | "generic";
+export interface SessionReference {
+    kind: SessionReferenceKind;
+    /** The URL exactly as it was written, so click-through is never lossy. */
+    url: string;
+    host: string;
+    /**
+     * Provider-scoped project path: `dev_squad/repo/tooling/paseo` on GitLab,
+     * `owner/repo` on GitHub, the site host on Jira. Null when the shape did not
+     * carry one.
+     */
+    project: string | null;
+    /** Pipeline id, MR iid, PR number, or issue key. Null for `generic`. */
+    id: string | null;
+    /** Compact label for a chip: `!123`, `#45`, `PENG-12`, `pipeline 2009`. */
+    label: string;
+}
+/**
+ * Classify one URL. Returns `null` only when the string is not a usable web
+ * URL at all -- an unrecognised host still comes back as `generic`, because a
+ * link the UI cannot enrich is still a link the UI should show.
+ */
+export declare function classifySessionReference(rawUrl: string): SessionReference | null;
+/** Classify many, dropping unusable strings and de-duplicating by URL. */
+export declare function classifySessionReferences(rawUrls: readonly string[]): SessionReference[];
+/** True when the daemon has a fetcher that can say something about this kind. */
+export declare function isEnrichableReference(reference: SessionReference): boolean;
+//# sourceMappingURL=session-references.d.ts.map

package/dist/session-references.js

@@ -0,0 +1,175 @@
+/**
+ * Session references -- turning a bare URL sitting in a session's digest into
+ * something the UI can render as a card instead of a link.
+ *
+ * The split matters. Classification is **pure and local**: given a URL string,
+ * decide what it is and pull the ids out of the path. Enrichment (is that
+ * pipeline green? what is that ticket called?) needs credentials and a network
+ * hop, so it lives on the daemon (`enrich_reference_request`) and never here.
+ *
+ * That split is the whole reason the app can show a useful reference card for a
+ * GitLab pipeline the instant the URL lands, and fill in "running / 12 of 14
+ * jobs" a moment later, without ever holding a provider token itself.
+ */
+/**
+ * GitLab nests groups arbitrarily deep, so the project path is everything
+ * before the `/-/` separator. Anything after it is the resource.
+ */
+const GITLAB_RESOURCE_SEPARATOR = "/-/";
+const JIRA_ISSUE_KEY = /^[A-Z][A-Z0-9]+-\d+$/;
+function safeParse(rawUrl) {
+    const trimmed = rawUrl.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return null;
+    }
+    // Only web references get cards. A `file://` or `mailto:` is still a link,
+    // just not something a provider can be asked about.
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return null;
+    }
+    return parsed;
+}
+function segments(pathname) {
+    return pathname.split("/").filter((segment) => segment.length > 0);
+}
+function generic(url, parsed) {
+    return {
+        kind: "generic",
+        url,
+        host: parsed.host,
+        project: null,
+        id: null,
+        label: parsed.host,
+    };
+}
+function classifyGitLab(url, parsed) {
+    const separatorIndex = parsed.pathname.indexOf(GITLAB_RESOURCE_SEPARATOR);
+    if (separatorIndex === -1) {
+        return null;
+    }
+    const project = segments(parsed.pathname.slice(0, separatorIndex)).join("/");
+    const resource = segments(parsed.pathname.slice(separatorIndex + GITLAB_RESOURCE_SEPARATOR.length));
+    if (project.length === 0 || resource.length < 2) {
+        return null;
+    }
+    const [kind, id] = resource;
+    if (kind === "pipelines" && /^\d+$/.test(id)) {
+        return {
+            kind: "gitlab-pipeline",
+            url,
+            host: parsed.host,
+            project,
+            id,
+            label: `pipeline ${id}`,
+        };
+    }
+    if (kind === "merge_requests" && /^\d+$/.test(id)) {
+        return {
+            kind: "gitlab-merge-request",
+            url,
+            host: parsed.host,
+            project,
+            id,
+            label: `!${id}`,
+        };
+    }
+    return null;
+}
+function classifyGitHub(url, parsed) {
+    if (parsed.host !== "github.com" && !parsed.host.endsWith(".github.com")) {
+        return null;
+    }
+    const parts = segments(parsed.pathname);
+    if (parts.length < 4) {
+        return null;
+    }
+    const [owner, repo, resource, id] = parts;
+    if (resource !== "pull" || !/^\d+$/.test(id)) {
+        return null;
+    }
+    return {
+        kind: "github-pull-request",
+        url,
+        host: parsed.host,
+        project: `${owner}/${repo}`,
+        id,
+        label: `#${id}`,
+    };
+}
+/**
+ * Jira writes the same issue two ways: the canonical `/browse/KEY-1`, and a
+ * board URL that carries the issue in `?selectedIssue=KEY-1`. Both are what a
+ * human actually pastes, so both resolve to the same card.
+ */
+function classifyJira(url, parsed) {
+    const selected = parsed.searchParams.get("selectedIssue");
+    if (selected && JIRA_ISSUE_KEY.test(selected)) {
+        return {
+            kind: "jira-issue",
+            url,
+            host: parsed.host,
+            project: parsed.host,
+            id: selected,
+            label: selected,
+        };
+    }
+    const parts = segments(parsed.pathname);
+    const browseIndex = parts.indexOf("browse");
+    if (browseIndex === -1) {
+        return null;
+    }
+    const key = parts[browseIndex + 1];
+    if (!key || !JIRA_ISSUE_KEY.test(key)) {
+        return null;
+    }
+    return {
+        kind: "jira-issue",
+        url,
+        host: parsed.host,
+        project: parsed.host,
+        id: key,
+        label: key,
+    };
+}
+/**
+ * Classify one URL. Returns `null` only when the string is not a usable web
+ * URL at all -- an unrecognised host still comes back as `generic`, because a
+ * link the UI cannot enrich is still a link the UI should show.
+ */
+export function classifySessionReference(rawUrl) {
+    const parsed = safeParse(rawUrl);
+    if (!parsed) {
+        return null;
+    }
+    const url = rawUrl.trim();
+    return (classifyGitLab(url, parsed) ??
+        classifyGitHub(url, parsed) ??
+        classifyJira(url, parsed) ??
+        generic(url, parsed));
+}
+/** Classify many, dropping unusable strings and de-duplicating by URL. */
+export function classifySessionReferences(rawUrls) {
+    const seen = new Set();
+    const out = [];
+    for (const rawUrl of rawUrls) {
+        const reference = classifySessionReference(rawUrl);
+        if (!reference || seen.has(reference.url)) {
+            continue;
+        }
+        seen.add(reference.url);
+        out.push(reference);
+    }
+    return out;
+}
+/** True when the daemon has a fetcher that can say something about this kind. */
+export function isEnrichableReference(reference) {
+    return reference.kind !== "generic";
+}
+//# sourceMappingURL=session-references.js.map

package/dist/session-secrets.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Session secrets -- the credential rows a session's context rail shows.
+ *
+ * The point of this module is one rule, and the rule is the reason it is in the
+ * protocol package rather than the app: **a secret is masked on the way IN, at
+ * the daemon boundary, never on the way out at the UI.**
+ *
+ * A masked-at-render design puts the real string in the snapshot, the push
+ * payload, the query cache and every log line that ever prints one, and asks
+ * the view layer to be careful forever. Masking at write means the dangerous
+ * value never enters paseo at all, so the reveal button can only ever uncover
+ * something that was already safe to hold.
+ */
+/** True when `value` looks like something that would still work if pasted. */
+export declare function looksLikeLiveSecret(value: string): boolean;
+/**
+ * Replace a value with something safe to store and render. Keeps a short tail
+ * so "is this the same token I put in the CI variable?" stays answerable, which
+ * is the only reason to show a credential row at all.
+ */
+export declare function maskSecretValue(value: string): string;
+export interface NormalizedSecret {
+    value: string;
+    masked: boolean;
+}
+/**
+ * The daemon-boundary call. Give it whatever the hook found; get back what is
+ * safe to persist, plus whether it had to be masked.
+ *
+ * `declaredMasked` lets a caller that already masked upstream say so, and is
+ * ignored when the value still looks live -- a caller cannot assert its way
+ * past the check.
+ */
+export declare function normalizeSecretForStorage(value: string, declaredMasked?: boolean): NormalizedSecret;
+//# sourceMappingURL=session-secrets.d.ts.map

package/dist/session-secrets.js

@@ -0,0 +1,133 @@
+/**
+ * Session secrets -- the credential rows a session's context rail shows.
+ *
+ * The point of this module is one rule, and the rule is the reason it is in the
+ * protocol package rather than the app: **a secret is masked on the way IN, at
+ * the daemon boundary, never on the way out at the UI.**
+ *
+ * A masked-at-render design puts the real string in the snapshot, the push
+ * payload, the query cache and every log line that ever prints one, and asks
+ * the view layer to be careful forever. Masking at write means the dangerous
+ * value never enters paseo at all, so the reveal button can only ever uncover
+ * something that was already safe to hold.
+ */
+/**
+ * Shapes that are live credentials by construction. These are matched on the
+ * VALUE, so the caller does not get to opt out by naming the field innocently.
+ *
+ * Deliberately conservative: it is fine to mask a harmless string, and not fine
+ * to store a live one. When in doubt, this list masks.
+ */
+const LIVE_SECRET_PATTERNS = [
+    /\bglpat-[A-Za-z0-9_-]{12,}/, // GitLab personal access token
+    /\bglrt-[A-Za-z0-9_-]{12,}/, // GitLab runner token
+    /\bgh[pousr]_[A-Za-z0-9]{20,}/, // GitHub token family
+    /\bgithub_pat_[A-Za-z0-9_]{20,}/,
+    /\bsk-[A-Za-z0-9_-]{20,}/, // OpenAI-style
+    /\bsk-ant-[A-Za-z0-9_-]{20,}/, // Anthropic
+    /\bxox[abposr]-[A-Za-z0-9-]{10,}/, // Slack
+    /\bAKIA[0-9A-Z]{16}\b/, // AWS access key id
+    /\bASIA[0-9A-Z]{16}\b/, // AWS temporary access key id
+    /\bAIza[0-9A-Za-z_-]{30,}/, // Google API key
+    /\bey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, // JWT
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+];
+/**
+ * Backstop for providers whose prefix nobody has added yet. New vendors mint new
+ * prefixes constantly, so length alone used to be the rule here -- and that was
+ * wrong in a way only running it revealed: a preview hostname
+ * (`paseo-app-preview-feat-session-context-rail.workers.dev`) was masked, which
+ * is the exact opposite of useful, since a connection hint is half the reason
+ * this section exists.
+ *
+ * Entropy is NOT the fix. Measured against real samples, a 32-char hex key
+ * scores 3.91 bits/char and that hostname scores 3.95: any threshold that
+ * catches the key also catches the hostname. What DOES separate them is the
+ * longest unbroken alphanumeric run, because human-readable identifiers are
+ * words joined by separators and credentials are not:
+ *
+ *   hostname / path / branch / email .... longest run 7-8
+ *   AWS secret key ...................... 13
+ *   base64 blob, hex key ................ 30+
+ */
+const OPAQUE_MIN_LENGTH = 24;
+const OPAQUE_SHAPE = /^[A-Za-z0-9+/=_.-]+$/;
+const OPAQUE_MIN_RUN = 12;
+function longestAlphanumericRun(value) {
+    let longest = 0;
+    let current = 0;
+    for (const char of value) {
+        if (/[A-Za-z0-9]/.test(char)) {
+            current += 1;
+            longest = Math.max(longest, current);
+        }
+        else {
+            current = 0;
+        }
+    }
+    return longest;
+}
+/**
+ * Shapes that are addresses, not credentials. A URL, a hostname, an email and
+ * a filesystem path are exactly the connection hints the rail is meant to show,
+ * so they short-circuit the length backstop. They do NOT short-circuit the
+ * vendor patterns above: a JWT contains dots and is still a JWT.
+ */
+function isHumanReadableHint(value) {
+    if (value.includes("://") || value.includes("@")) {
+        return true;
+    }
+    if (/^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(value)) {
+        return true;
+    }
+    return value.startsWith("/") || value.startsWith("~/") || value.startsWith("./");
+}
+/** True when `value` looks like something that would still work if pasted. */
+export function looksLikeLiveSecret(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return false;
+    }
+    // Vendor prefixes are decisive and are checked first, so a token that happens
+    // to contain a dot or a slash is never argued out of being a token.
+    if (LIVE_SECRET_PATTERNS.some((pattern) => pattern.test(trimmed))) {
+        return true;
+    }
+    if (isHumanReadableHint(trimmed)) {
+        return false;
+    }
+    return (trimmed.length >= OPAQUE_MIN_LENGTH &&
+        OPAQUE_SHAPE.test(trimmed) &&
+        longestAlphanumericRun(trimmed) >= OPAQUE_MIN_RUN);
+}
+/** How many trailing characters a mask keeps so a human can tell two apart. */
+const MASK_TAIL = 4;
+const MASK_BULLETS = "••••";
+/**
+ * Replace a value with something safe to store and render. Keeps a short tail
+ * so "is this the same token I put in the CI variable?" stays answerable, which
+ * is the only reason to show a credential row at all.
+ */
+export function maskSecretValue(value) {
+    const trimmed = value.trim();
+    if (trimmed.length <= MASK_TAIL) {
+        return MASK_BULLETS;
+    }
+    return `${MASK_BULLETS}${trimmed.slice(-MASK_TAIL)}`;
+}
+/**
+ * The daemon-boundary call. Give it whatever the hook found; get back what is
+ * safe to persist, plus whether it had to be masked.
+ *
+ * `declaredMasked` lets a caller that already masked upstream say so, and is
+ * ignored when the value still looks live -- a caller cannot assert its way
+ * past the check.
+ */
+export function normalizeSecretForStorage(value, declaredMasked) {
+    const trimmed = value.trim();
+    if (looksLikeLiveSecret(trimmed)) {
+        return { value: maskSecretValue(trimmed), masked: true };
+    }
+    return { value: trimmed, masked: declaredMasked ?? false };
+}
+//# sourceMappingURL=session-secrets.js.map