@kontourai/flow-agents 3.12.1 → 4.1.0

package/dist/codex/build/src/narrative/source-ids.d.ts

@@ -0,0 +1,121 @@
+export declare const NARRATIVE_SOURCE_ID_VERSION: "fa1";
+export type NarrativeSourceStream = "telemetry" | "cmdlog" | "agent-event" | "delegation" | "trust-claim" | "trust-evidence" | "flow-state" | "flow-report" | "flow-transition" | "surface-explanation" | "transcript" | "file";
+interface SourceIdBase<S extends NarrativeSourceStream> {
+    version: typeof NARRATIVE_SOURCE_ID_VERSION;
+    stream: S;
+}
+export interface TelemetrySourceId extends SourceIdBase<"telemetry"> {
+    scope: {
+        channel: string;
+        sessionId: string;
+    };
+    locator: {
+        eventId: string;
+        sha8: string;
+    };
+    ordinal?: number;
+}
+export interface ChainedCommandLogSourceId extends SourceIdBase<"cmdlog"> {
+    scope: {
+        slug: string;
+    };
+    locator: {
+        kind: "chained";
+        seq: number;
+        hash8: string;
+    };
+}
+export interface LegacyCommandLogSourceId extends SourceIdBase<"cmdlog"> {
+    scope: {
+        slug: string;
+    };
+    locator: {
+        kind: "legacy";
+        line: number;
+        sha8: string;
+    };
+}
+export type CommandLogSourceId = ChainedCommandLogSourceId | LegacyCommandLogSourceId;
+export interface AgentEventSourceId extends SourceIdBase<"agent-event" | "delegation"> {
+    scope: {
+        slug: string;
+        agentId: string;
+    };
+    locator: {
+        lineIndex: number;
+        sha8: string;
+    };
+}
+export interface TrustSourceId extends SourceIdBase<"trust-claim" | "trust-evidence"> {
+    scope: {
+        slug: string;
+        bundleSha8: string;
+    };
+    locator: {
+        id: string;
+    };
+}
+export interface FlowStateSourceId extends SourceIdBase<"flow-state"> {
+    scope: {
+        runId: string;
+    };
+    locator: {
+        sha8: string;
+    };
+}
+export interface FlowReportSourceId extends SourceIdBase<"flow-report"> {
+    scope: {
+        runId: string;
+    };
+    locator: {
+        sha8: string;
+    };
+}
+export interface FlowTransitionSourceId extends SourceIdBase<"flow-transition"> {
+    scope: {
+        runId: string;
+    };
+    locator: {
+        index: number;
+        sha8: string;
+    };
+}
+export interface SurfaceExplanationSourceId extends SourceIdBase<"surface-explanation"> {
+    scope: {
+        slug: string;
+        bundleSha8: string;
+    };
+    locator: {
+        claimId: string;
+    };
+}
+export interface TranscriptSourceId extends SourceIdBase<"transcript"> {
+    scope: {
+        pathSha8: string;
+    };
+    locator: {
+        byteStart: number;
+        byteEnd: number;
+    };
+}
+export interface FileSourceId extends SourceIdBase<"file"> {
+    scope: {
+        repoRelativePath: string;
+    };
+    locator: {
+        hash: string;
+        hashKind: "sha256" | "git-blob";
+    };
+}
+export type NarrativeSourceId = TelemetrySourceId | CommandLogSourceId | AgentEventSourceId | TrustSourceId | FlowStateSourceId | FlowReportSourceId | FlowTransitionSourceId | SurfaceExplanationSourceId | TranscriptSourceId | FileSourceId;
+export type SourceIdErrorCode = "invalid_syntax" | "unsupported_version" | "unsupported_stream" | "invalid_encoding" | "invalid_scope" | "invalid_locator" | "invalid_ordinal";
+export declare class SourceIdParseError extends Error {
+    readonly code: SourceIdErrorCode;
+    readonly sourceId: string;
+    readonly name = "SourceIdParseError";
+    constructor(code: SourceIdErrorCode, sourceId: string, message: string);
+}
+export declare function parseSourceId(sourceId: string): NarrativeSourceId;
+export declare function formatSourceId(source: NarrativeSourceId): string;
+export declare function compareSourceIds(left: NarrativeSourceId | string, right: NarrativeSourceId | string): number;
+export {};

package/dist/codex/build/src/narrative/source-ids.js

@@ -0,0 +1,201 @@
+export const NARRATIVE_SOURCE_ID_VERSION = "fa1";
+export class SourceIdParseError extends Error {
+    code;
+    sourceId;
+    name = "SourceIdParseError";
+    constructor(code, sourceId, message) {
+        super(message);
+        this.code = code;
+        this.sourceId = sourceId;
+    }
+}
+const STREAMS = new Set([
+    "telemetry", "cmdlog", "agent-event", "delegation", "trust-claim",
+    "trust-evidence", "flow-state", "flow-transition", "transcript", "file",
+    "flow-report", "surface-explanation",
+]);
+const ENCODED_COMPONENT = /^(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+$/;
+const SHA8 = /^[0-9a-f]{8}$/;
+const CONTENT_HASH = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+function fail(code, sourceId, message) {
+    throw new SourceIdParseError(code, sourceId, message);
+}
+function encodeComponent(value) {
+    if (!value)
+        throw new TypeError("source ID components must not be empty");
+    return encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function decodeComponent(value, sourceId) {
+    if (!ENCODED_COMPONENT.test(value))
+        fail("invalid_encoding", sourceId, "source ID component is not percent-encoded");
+    try {
+        const decoded = decodeURIComponent(value);
+        if (!decoded)
+            fail("invalid_encoding", sourceId, "source ID component must not be empty");
+        return decoded;
+    }
+    catch {
+        return fail("invalid_encoding", sourceId, "source ID component contains invalid percent encoding");
+    }
+}
+function splitComponents(value, count, sourceId, part) {
+    const pieces = value.split("/");
+    if (pieces.length !== count)
+        fail(part === "scope" ? "invalid_scope" : "invalid_locator", sourceId, `${part} must have ${count} component(s)`);
+    return pieces.map((piece) => decodeComponent(piece, sourceId));
+}
+function integer(value, sourceId, label, minimum = 0) {
+    if (!/^(?:0|[1-9][0-9]*)$/.test(value))
+        fail("invalid_locator", sourceId, `${label} must be a canonical integer`);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < minimum)
+        fail("invalid_locator", sourceId, `${label} is out of range`);
+    return parsed;
+}
+function sha8(value, sourceId, label) {
+    if (!SHA8.test(value))
+        fail("invalid_locator", sourceId, `${label} must be eight lowercase hexadecimal characters`);
+    return value;
+}
+function pathSafeScope(value, sourceId, label) {
+    if (value.includes("/") || value.includes("\\"))
+        fail("invalid_scope", sourceId, `${label} must not contain a path separator`);
+    return value;
+}
+export function parseSourceId(sourceId) {
+    const ordinalParts = sourceId.split("#");
+    if (ordinalParts.length > 2)
+        fail("invalid_syntax", sourceId, "source ID has more than one ordinal delimiter");
+    const [body = "", ordinalText] = ordinalParts;
+    const parts = body.split(":");
+    if (parts.length !== 4)
+        fail("invalid_syntax", sourceId, "source ID must have version, stream, scope, and locator");
+    const [version, streamText, rawScope, rawLocator] = parts;
+    if (version !== NARRATIVE_SOURCE_ID_VERSION)
+        fail("unsupported_version", sourceId, `unsupported source ID version: ${version || "(empty)"}`);
+    if (!STREAMS.has(streamText))
+        fail("unsupported_stream", sourceId, `unsupported source stream: ${streamText || "(empty)"}`);
+    const stream = streamText;
+    let ordinal;
+    if (ordinalText !== undefined) {
+        if (stream !== "telemetry" || !/^(?:0|[1-9][0-9]*)$/.test(ordinalText))
+            fail("invalid_ordinal", sourceId, "ordinal is only valid for telemetry and must be a canonical non-negative integer");
+        ordinal = Number(ordinalText);
+        if (!Number.isSafeInteger(ordinal))
+            fail("invalid_ordinal", sourceId, "ordinal is out of range");
+    }
+    switch (stream) {
+        case "telemetry": {
+            const [channel, sessionId] = splitComponents(rawScope, 2, sourceId, "scope");
+            const [eventId, hash] = splitComponents(rawLocator, 2, sourceId, "locator");
+            return { version, stream, scope: { channel, sessionId }, locator: { eventId, sha8: sha8(hash, sourceId, "telemetry content pin") }, ...(ordinal === undefined ? {} : { ordinal }) };
+        }
+        case "cmdlog": {
+            const [slug] = splitComponents(rawScope, 1, sourceId, "scope");
+            const [first, hash] = splitComponents(rawLocator, 2, sourceId, "locator");
+            const hashPin = sha8(hash, sourceId, "command-log hash pin");
+            if (first.startsWith("line-"))
+                return { version, stream, scope: { slug }, locator: { kind: "legacy", line: integer(first.slice(5), sourceId, "legacy line", 1), sha8: hashPin } };
+            return { version, stream, scope: { slug }, locator: { kind: "chained", seq: integer(first, sourceId, "chain sequence"), hash8: hashPin } };
+        }
+        case "agent-event":
+        case "delegation": {
+            const [slug, agentId] = splitComponents(rawScope, 2, sourceId, "scope");
+            const [index, hash] = splitComponents(rawLocator, 2, sourceId, "locator");
+            return { version, stream, scope: { slug, agentId }, locator: { lineIndex: integer(index, sourceId, "line index"), sha8: sha8(hash, sourceId, "line hash pin") } };
+        }
+        case "trust-claim":
+        case "trust-evidence": {
+            const [slug, bundleHash] = splitComponents(rawScope, 2, sourceId, "scope");
+            const [id] = splitComponents(rawLocator, 1, sourceId, "locator");
+            return { version, stream, scope: { slug, bundleSha8: sha8(bundleHash, sourceId, "bundle hash pin") }, locator: { id } };
+        }
+        case "flow-state": {
+            const [runId] = splitComponents(rawScope, 1, sourceId, "scope");
+            const [state, hash] = splitComponents(rawLocator, 2, sourceId, "locator");
+            if (state !== "state")
+                fail("invalid_locator", sourceId, "flow-state locator must begin with state");
+            return { version, stream, scope: { runId }, locator: { sha8: sha8(hash, sourceId, "state hash pin") } };
+        }
+        case "flow-report": {
+            const [decodedRunId] = splitComponents(rawScope, 1, sourceId, "scope");
+            const runId = pathSafeScope(decodedRunId, sourceId, "flow-report run ID");
+            const [report, hash] = splitComponents(rawLocator, 2, sourceId, "locator");
+            if (report !== "report")
+                fail("invalid_locator", sourceId, "flow-report locator must begin with report");
+            return { version, stream, scope: { runId }, locator: { sha8: sha8(hash, sourceId, "report hash pin") } };
+        }
+        case "flow-transition": {
+            const [runId] = splitComponents(rawScope, 1, sourceId, "scope");
+            const [index, hash] = splitComponents(rawLocator, 2, sourceId, "locator");
+            return { version, stream, scope: { runId }, locator: { index: integer(index, sourceId, "transition index"), sha8: sha8(hash, sourceId, "transition hash pin") } };
+        }
+        case "surface-explanation": {
+            const [decodedSlug, bundleHash] = splitComponents(rawScope, 2, sourceId, "scope");
+            const slug = pathSafeScope(decodedSlug, sourceId, "surface-explanation slug");
+            const [claimId] = splitComponents(rawLocator, 1, sourceId, "locator");
+            return { version, stream, scope: { slug, bundleSha8: sha8(bundleHash, sourceId, "bundle hash pin") }, locator: { claimId } };
+        }
+        case "transcript": {
+            const [pathHash] = splitComponents(rawScope, 1, sourceId, "scope");
+            const [range] = splitComponents(rawLocator, 1, sourceId, "locator");
+            const match = /^(0|[1-9][0-9]*)-(0|[1-9][0-9]*)$/.exec(range);
+            if (!match)
+                fail("invalid_locator", sourceId, "transcript locator must be a canonical byte range");
+            const byteStart = integer(match[1], sourceId, "byte start");
+            const byteEnd = integer(match[2], sourceId, "byte end");
+            if (byteEnd < byteStart)
+                fail("invalid_locator", sourceId, "transcript byte end must not precede byte start");
+            return { version, stream, scope: { pathSha8: sha8(pathHash, sourceId, "path hash pin") }, locator: { byteStart, byteEnd } };
+        }
+        case "file": {
+            const [repoRelativePath] = splitComponents(rawScope, 1, sourceId, "scope");
+            const [hash] = splitComponents(rawLocator, 1, sourceId, "locator");
+            if (!CONTENT_HASH.test(hash))
+                fail("invalid_locator", sourceId, "file hash pin must be a lowercase SHA-1 or SHA-256 digest");
+            return { version, stream, scope: { repoRelativePath }, locator: { hash, hashKind: hash.length === 64 ? "sha256" : "git-blob" } };
+        }
+    }
+}
+export function formatSourceId(source) {
+    const prefix = `${NARRATIVE_SOURCE_ID_VERSION}:${source.stream}:`;
+    switch (source.stream) {
+        case "telemetry":
+            return `${prefix}${encodeComponent(source.scope.channel)}/${encodeComponent(source.scope.sessionId)}:${encodeComponent(source.locator.eventId)}/${source.locator.sha8}${source.ordinal === undefined ? "" : `#${source.ordinal}`}`;
+        case "cmdlog":
+            return source.locator.kind === "legacy"
+                ? `${prefix}${encodeComponent(source.scope.slug)}:line-${source.locator.line}/${source.locator.sha8}`
+                : `${prefix}${encodeComponent(source.scope.slug)}:${source.locator.seq}/${source.locator.hash8}`;
+        case "agent-event":
+        case "delegation":
+            return `${prefix}${encodeComponent(source.scope.slug)}/${encodeComponent(source.scope.agentId)}:${source.locator.lineIndex}/${source.locator.sha8}`;
+        case "trust-claim":
+        case "trust-evidence":
+            return `${prefix}${encodeComponent(source.scope.slug)}/${source.scope.bundleSha8}:${encodeComponent(source.locator.id)}`;
+        case "flow-state":
+            return `${prefix}${encodeComponent(source.scope.runId)}:state/${source.locator.sha8}`;
+        case "flow-report":
+            {
+                const formatted = `${prefix}${encodeComponent(source.scope.runId)}:report/${source.locator.sha8}`;
+                pathSafeScope(source.scope.runId, formatted, "flow-report run ID");
+                return formatted;
+            }
+        case "flow-transition":
+            return `${prefix}${encodeComponent(source.scope.runId)}:${source.locator.index}/${source.locator.sha8}`;
+        case "surface-explanation":
+            {
+                const formatted = `${prefix}${encodeComponent(source.scope.slug)}/${source.scope.bundleSha8}:${encodeComponent(source.locator.claimId)}`;
+                pathSafeScope(source.scope.slug, formatted, "surface-explanation slug");
+                return formatted;
+            }
+        case "transcript":
+            return `${prefix}${source.scope.pathSha8}:${source.locator.byteStart}-${source.locator.byteEnd}`;
+        case "file":
+            return `${prefix}${encodeComponent(source.scope.repoRelativePath)}:${source.locator.hash}`;
+    }
+}
+export function compareSourceIds(left, right) {
+    const leftText = typeof left === "string" ? formatSourceId(parseSourceId(left)) : formatSourceId(left);
+    const rightText = typeof right === "string" ? formatSourceId(parseSourceId(right)) : formatSourceId(right);
+    return leftText < rightText ? -1 : leftText > rightText ? 1 : 0;
+}

package/dist/codex/build/src/narrative/statements.d.ts

@@ -0,0 +1,84 @@
+import type { UnavailableReason } from "./integrity.js";
+export type StatementClass = "observed" | "deterministic_derived" | "summarizer_inferred" | "agent_stated";
+export type ObservedResult = "pass" | "fail" | "ambiguous";
+export declare const AGENT_STATED_PURPOSE_MAX_LENGTH = 200;
+export declare const AGENT_STATED_ACTOR_MAX_LENGTH = 120;
+export interface StatementRule {
+    id: string;
+    version: string;
+    inputs: string[];
+}
+export interface Statement {
+    id: string;
+    class: StatementClass;
+    proposition: string;
+    source_refs: string[];
+    turn_ref?: number;
+    actor?: string;
+    rule?: StatementRule;
+    self_report?: true;
+}
+export type NarrativeStatementErrorCode = "invalid_input" | "invalid_source_ref" | "invalid_rule" | "non_atomic_proposition";
+export declare class NarrativeStatementError extends Error {
+    readonly code: NarrativeStatementErrorCode;
+    readonly name = "NarrativeStatementError";
+    constructor(code: NarrativeStatementErrorCode, message: string);
+}
+export declare function observedCommand(input: {
+    sourceId: string;
+    command: string;
+    observedResult: ObservedResult;
+    exitCode: number | null;
+    actor?: string;
+}): Statement;
+export declare function observedToolAction(input: {
+    sourceId: string;
+    toolName: string;
+    eventType: string;
+    actor?: string;
+}): Statement;
+export declare function observedDelegation(input: {
+    sourceId: string;
+    agentId?: string | null;
+    targets?: string[];
+}): Statement;
+export declare function observedFileCreation(input: {
+    sourceId: string;
+    path: string;
+}): Statement;
+export declare function derivedRetry(input: {
+    sourceIds: string[];
+    command: string;
+    attempts: number;
+    ruleInputs: string[];
+}): Statement;
+export declare function derivedNoOpTurn(input: {
+    turnRef: number;
+    sourceIds: string[];
+}): Statement;
+export declare function derivedTimeout(input: {
+    sourceId: string;
+    operation: string;
+    timeoutMs?: number;
+}): Statement;
+export declare function derivedUnavailableSource(input: {
+    sourceId: string;
+    reason: UnavailableReason;
+}): Statement;
+export declare function summarizerInferredConnective(input: {
+    id?: string;
+    proposition: string;
+    source_refs: string[];
+    turn_ref?: number;
+    actor?: string;
+}): Statement;
+export declare function agentStatedIntent(input: {
+    sourceId: string;
+    purpose: string;
+    actor: string;
+    turnRef?: number;
+}): Statement;
+export declare function workflowDerivedPurpose(input: {
+    activeGateRef: string;
+    objectiveRef?: string;
+}): Statement;