@sema-agent/core/dist/core/arg-summary.d.ts

Stateless, task-oriented AI agent core

/** Known credential SHAPES + `secretKey=value` — redacted from the FINAL abbreviated string, the single scrub
 *  point before any store/SSE fan-out. Conservative (real credential formats). */
/** every prefix is LEFT-ANCHORED with \`(?<![A-Za-z0-9])\` — without it, ordinary words whose
 *  TAIL spells a prefix were silently redacted (NETWORK-attached → NETWO[redacted], RTMARK-100,
 *  task_categories, monkey=abcd1234, MonkeyJumping…) while triggering unpredictably on suffix
 *  length. \`_\` is deliberately NOT in the anchor class: \`api_key=\`, \`STRIPE=sk_live_…\`-style glued
 *  assignments are REAL credential shapes that must keep scrubbing. The prefixed-token arm also
 *  drops the \`i\` flag: the real vendors' prefixes are lowercase-only (sk_/pk_/rk_/ghp_…), and the
 *  case-insensitive form is what turned every UPPERCASE technical word ending in RK/SK/PK into a
 *  false positive. */
export type RedactionConfidence = "high" | "medium" | "low";
/** Which module's rule table minted a finding (ANG-11 provenance). A closed set, and there is no public
 *  factory for a finding — a report's entries can only have been written by one of these tables running
 *  here, so "this finding says X" is an engine statement, not something a caller can hand-assemble into
 *  a report and have the pipeline endorse. */
export type RedactionSource = "arg-summary" | "untrusted-egress" | "secret-env";
/** One redaction hit: what was detected, where (ORIGINAL-input coordinates), how confidently, the marker
 *  literal written in its place, and which rule table minted it. */
export interface RedactionFinding {
    kind: string;
    span: readonly [number, number];
    confidence: RedactionConfidence;
    marker: string;
    source: RedactionSource;
}
/** The minimum a finding must declare to be summarizable. Both text findings ({@link RedactionFinding})
 *  and the env arm's entry findings satisfy it, so {@link summarizeRedactions} is ONE helper rather than
 *  one per material kind. */
export interface SummarizableFinding {
    kind: string;
    confidence: RedactionConfidence;
}
/** ANG-3 (envelope declaration) — render findings as ONE human-readable line, e.g.
 *  `"3 redactions: prefixed-token (high) x1, url (medium) x1, fs-path (low) x1"`, so an upper layer can
 *  declare to its consumer how much was removed and how confidently.
 *
 *  PURE, and deliberately only that: it reads the array, returns a string, and injects nothing anywhere.
 *  Attaching this line to an output is the caller's decision — a redaction pipeline that silently
 *  appended prose to the very text it was asked to bound would break both the size contract
 *  (`boundedString`) and the byte-invariance the whole channel is built on.
 *
 *  Grouping is by kind AND confidence together: collapsing on kind alone would report whichever
 *  confidence happened to arrive first for the rest of that group, which is exactly the silent
 *  mis-statement ANG-4 exists to prevent. */
export declare function summarizeRedactions(findings: readonly SummarizableFinding[]): string;
/** The optional collector every redaction entry point accepts. `preexistingMarkers` (ANG-11) counts
 *  marker-shaped literals ALREADY present in the input before any pass ran — a nonzero value means the
 *  text arrived pre-redacted or carries caller-declared markers, either way "marker present" is not proof this
 *  pipeline ran. Caller-owned: pass `{ findings: [] }` and read it back after the call. */
export interface RedactionReport {
    findings: RedactionFinding[];
    preexistingMarkers?: number;
}
/** A declared redaction pass — the unit {@link runRedactionPasses} executes and reports on. */
export interface RedactionPass {
    kind: string;
    confidence: RedactionConfidence;
    marker: string;
    /** The module this pass is declared in — copied verbatim onto every finding it mints (ANG-11). It
     *  travels WITH the pass, so a table composed into another module's pipeline (untrusted-egress chains
     *  {@link SECRET_PASSES}) still attributes its hits to the table that owns the rule, not to whoever ran it. */
    source: RedactionSource;
    re: RegExp;
    /** A literal replacement (only `$1` substitution is used by these passes) or a replacer fn. */
    replace: string | ((match: string, ...groups: string[]) => string);
}
/**
 * Run the declared passes in order, collecting findings (original-input spans) when a report is given.
 *
 * FORMAT CHARACTERS (#532): the passes scan a VIEW of the input with every `\p{Cf}` removed, so a
 * credential split by a zero-width character is one token to the scanner, not two fragments of which
 * only the first (or neither) matches. The OUTPUT keeps every format character that sits OUTSIDE a
 * replaced span — a joiner in an emoji sequence, a non-joiner in Persian text, a soft hyphen in a word
 * — and drops only those INSIDE the span the marker replaces (they were part of the secret). A
 * format-free input takes the exact historical path (byte-identical output). When the replacements
 * cannot be mapped back exactly (a later pass matched across an earlier pass's inserted text), the
 * output is the redacted view itself — every format character dropped: the failure direction is
 * over-stripping, never a leak.
 */
export declare function runRedactionPasses(input: string, passes: readonly RedactionPass[], report?: RedactionReport): string;
/** The credential-shape passes (the pre-channel SECRET_PATTERNS, now with declared kinds/confidence).
 *  Exported for {@link runRedactionPasses} composition (untrusted-egress chains its URL passes after
 *  these in ONE pipeline so its findings' spans stay in original coordinates). */
export declare const SECRET_PASSES: readonly RedactionPass[];
export declare function scrubSecrets(s: string, report?: RedactionReport): string;
/** A SHORT, SECRET-SCRUBBED primary-arg summary. Abbreviation REDUCES the surface; a final {@link scrubSecrets}
 *  pass is the leak boundary (the value is PERSISTED + SSE-forwarded and may be read by a platform operator in a
 *  multi-tenant deployment). Rules:
 *   • command → the command NAME (skip leading `VAR=val` env-prefixes; bail to `undefined` on a quoted assignment
 *     or a lone assignment; basename a path-form command; `+ …` if it had args).
 *   • file path → BASENAME only (no host directory layout).
 *   • url → `new URL` origin+pathname (strips `user:pass@` userinfo + query/fragment).
 *   • else → pattern/query/description, else the first NON-sensitively-named string field.
 *  Then scrub-secrets + code-point-truncate. */
export declare function primaryActivityArg(args: unknown): string | undefined;