@oxygen-agent/cli 1.893.0 → 1.906.0

package/node_modules/@oxygen/shared/dist/copilot-plan.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The four states a plan step may be in.
+ *
+ * This is the vocabulary `plan_update`'s JSON Schema enforces going forward, and
+ * @oxygen/agent-runtime imports it so the schema and this reader can never drift.
+ */
+export declare const COPILOT_PLAN_STEP_STATUSES: readonly ["pending", "in_progress", "done", "blocked"];
+export type CopilotPlanStepStatus = (typeof COPILOT_PLAN_STEP_STATUSES)[number];
+/**
+ * An unrecognised status resolves to `pending`, never to `done`.
+ *
+ * This is the fail-closed direction and it is deliberate. Resolving the unknown
+ * to `done` would let a typo report a run as finished and silence the open-steps
+ * nudge; resolving it to `pending` at worst leaves a finished step looking open,
+ * which is visible and self-correcting on the next plan update.
+ */
+export declare function normalizeCopilotPlanStepStatus(raw: unknown): CopilotPlanStepStatus;
+/** A step is open until it is done. `blocked` is open too -- it still owes an outcome. */
+export declare function isCopilotPlanStepOpen(step: {
+    status: CopilotPlanStepStatus;
+}): boolean;
+/**
+ * The step shape after normalisation, before any timing is attached.
+ *
+ * `title` accepts three spellings because three have been produced: the tool
+ * schema and `packages/copilot`'s dormant `PlanStep` type both say `title`, while
+ * the model actually shipped `description` on every step of session 4097ef0d.
+ * `parsePlanSteps` in the web app required `title` and `continue`d past anything
+ * else, which is why it returned null for every real payload ever written.
+ */
+export type CopilotPlanRawStep = {
+    id: string | null;
+    title: string;
+    status: CopilotPlanStepStatus;
+    estimateSeconds: number | null;
+    substeps: Array<{
+        id: string | null;
+        title: string;
+        status: CopilotPlanStepStatus;
+    }>;
+};
+/**
+ * Pull the step list out of a `plan_updated` payload.
+ *
+ * Accepts both `{steps}` at the root (what the runtime emits) and the nested
+ * `{plan:{steps}}` shape, so a payload written by either producer renders.
+ */
+export declare function readCopilotPlanPayload(payload: Record<string, unknown> | null | undefined): {
+    summary: string;
+    steps: CopilotPlanRawStep[];
+} | null;
+/** Where a step's ETA came from. Rendered beside the number, never hidden. */
+export type CopilotPlanEtaBasis = 
+/** A model estimate scaled by how wrong its estimates have been so far. */
+"calibrated"
+/** No usable estimate; the mean of this turn's own completed steps. */
+ | "measured"
+/** The model's estimate, with nothing completed yet to calibrate it. */
+ | "model"
+/** Nothing to go on. The surface must say so rather than invent a number. */
+ | "none";
+export type CopilotPlanSubstep = {
+    id: string;
+    title: string;
+    status: CopilotPlanStepStatus;
+    /** `model` when the model declared it, `tool` when it is an observed call. */
+    source: "model" | "tool";
+    durationMs: number | null;
+    startedAt: string | null;
+    /**
+     * Set only for a `subagent_run`. A sub-agent's own capability calls never reach
+     * the ledger (it is handed capability tools directly, bypassing the runtime tool
+     * path), so the rollup counts are all there is -- and the rail must not imply a
+     * deeper trace exists.
+     */
+    subagent?: {
+        name: string;
+        inferences: number;
+        capabilityCalls: number;
+    };
+};
+export type CopilotPlanStep = {
+    id: string;
+    title: string;
+    status: CopilotPlanStepStatus;
+    estimateSeconds: number | null;
+    startedAt: string | null;
+    endedAt: string | null;
+    /** Wall time the step has taken, or took. Null until it starts. */
+    elapsedMs: number | null;
+    /** Seconds still expected. Null for a done step, or when nothing can be said. */
+    etaSeconds: number | null;
+    etaBasis: CopilotPlanEtaBasis;
+    substeps: CopilotPlanSubstep[];
+};
+export type CopilotPlanProjection = {
+    summary: string | null;
+    steps: CopilotPlanStep[];
+    progress: {
+        done: number;
+        total: number;
+        ratio: number;
+    };
+    eta: {
+        remainingSeconds: number | null;
+        basis: CopilotPlanEtaBasis;
+        /** How many completed, timed steps the measurement rests on. */
+        measuredSteps: number;
+        /** True when the turn's wall-clock deadline, not the plan, is the binding bound. */
+        deadlineBound: boolean;
+    };
+    /** Ledger position of the newest plan_updated, so a caller can tell staleness. */
+    updatedAtSeq: number;
+    updatedAt: string;
+};
+export type CopilotPlanSourceEvent = {
+    seq: number;
+    kind: string;
+    payload: Record<string, unknown> | null;
+    created_at: string | Date;
+};
+export type ProjectCopilotPlanInput = {
+    /** Ordered by seq. Only plan_updated / tool_call_* / context_assembled are read. */
+    events: CopilotPlanSourceEvent[];
+    /** The active turn's wall-clock deadline, used only to clamp the total. */
+    turnDeadlineAt?: string | Date | null;
+    now?: Date;
+};
+/**
+ * Rebuild the plan, with timings, from the session's event ledger.
+ *
+ * Returns null when the session has never published a plan -- which is the correct
+ * answer for a trivial turn, since the prompt tells the model to skip `plan_update`
+ * entirely and call `finish`. A rail that renders an empty shell for every greeting
+ * would be worse than one that stays away.
+ */
+export declare function projectCopilotPlan(input: ProjectCopilotPlanInput): CopilotPlanProjection | null;

package/node_modules/@oxygen/shared/dist/copilot-plan.js

@@ -0,0 +1,435 @@
+// The Copilot's plan, as a surface can render it: major steps, their substeps,
+// and a timed projection of what is left.
+//
+// The plan itself is not new -- the shared runtime has published a `plan_update`
+// tool and written a `plan_updated` event since the Strands cut-over. What was
+// missing is anything that READS it. This module is that reader, and it lives in
+// @oxygen/shared for one reason: web, CLI and MCP must show the same numbers, and
+// the only way to guarantee that is for there to be one implementation of them.
+// The web surface renders what the API computed here; it does not re-derive.
+//
+// TIME IS DERIVED, NOT STORED. `copilot_events` carries a single `created_at` per
+// row -- there is no per-step duration column anywhere, and there is no ETA field
+// in the tool schema, the payload, or the DB. Everything below is reconstructed
+// from the ordered ledger, which is also why every number reports the BASIS it
+// rests on: a projection that cannot say where its estimate came from is not
+// inspectable, and an uninspectable number on a progress rail is worse than no
+// number at all.
+/**
+ * The four states a plan step may be in.
+ *
+ * This is the vocabulary `plan_update`'s JSON Schema enforces going forward, and
+ * @oxygen/agent-runtime imports it so the schema and this reader can never drift.
+ */
+export const COPILOT_PLAN_STEP_STATUSES = ["pending", "in_progress", "done", "blocked"];
+/**
+ * Forgiving on read, strict on write.
+ *
+ * The tool schema now pins the enum, but the ledger is append-only and already
+ * holds events written when `steps` was `{type:"object", additionalProperties:true}`
+ * with no validation at all. Session 4097ef0d wrote `status: "completed"` -- which
+ * `hasOpenPlanSteps` (testing `status !== "done"`) read as an OPEN step, misfiring
+ * the stop-nudge on a plan that was finished. Normalising on read is what lets one
+ * predicate serve both the historical rows and the schema-constrained ones.
+ */
+const STATUS_ALIASES = {
+    pending: "pending",
+    todo: "pending",
+    not_started: "pending",
+    "not-started": "pending",
+    planned: "pending",
+    queued: "pending",
+    in_progress: "in_progress",
+    "in-progress": "in_progress",
+    inprogress: "in_progress",
+    running: "in_progress",
+    active: "in_progress",
+    started: "in_progress",
+    working: "in_progress",
+    done: "done",
+    complete: "done",
+    completed: "done",
+    finished: "done",
+    succeeded: "done",
+    success: "done",
+    blocked: "blocked",
+    failed: "blocked",
+    error: "blocked",
+    stuck: "blocked",
+};
+/**
+ * An unrecognised status resolves to `pending`, never to `done`.
+ *
+ * This is the fail-closed direction and it is deliberate. Resolving the unknown
+ * to `done` would let a typo report a run as finished and silence the open-steps
+ * nudge; resolving it to `pending` at worst leaves a finished step looking open,
+ * which is visible and self-correcting on the next plan update.
+ */
+export function normalizeCopilotPlanStepStatus(raw) {
+    if (typeof raw !== "string")
+        return "pending";
+    return STATUS_ALIASES[raw.trim().toLowerCase()] ?? "pending";
+}
+/** A step is open until it is done. `blocked` is open too -- it still owes an outcome. */
+export function isCopilotPlanStepOpen(step) {
+    return step.status !== "done";
+}
+function readText(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function readEstimateSeconds(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        return null;
+    // Same bounds the tool schema advertises. A model that ignores them does not get
+    // to skew the calibration factor with a 40-hour step.
+    return Math.min(Math.max(Math.round(value), 5), 3600);
+}
+function readRawStep(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const obj = raw;
+    const title = readText(obj.title) || readText(obj.description) || readText(obj.name);
+    if (title.length === 0)
+        return null;
+    const substeps = [];
+    if (Array.isArray(obj.substeps)) {
+        for (const rawSub of obj.substeps) {
+            if (!rawSub || typeof rawSub !== "object")
+                continue;
+            const sub = rawSub;
+            const subTitle = readText(sub.title) || readText(sub.description) || readText(sub.name);
+            if (subTitle.length === 0)
+                continue;
+            substeps.push({
+                id: readText(sub.id) || null,
+                title: subTitle,
+                status: normalizeCopilotPlanStepStatus(sub.status),
+            });
+        }
+    }
+    return {
+        id: readText(obj.id) || null,
+        title,
+        status: normalizeCopilotPlanStepStatus(obj.status),
+        estimateSeconds: readEstimateSeconds(obj.estimate_seconds ?? obj.estimateSeconds),
+        substeps,
+    };
+}
+/**
+ * Pull the step list out of a `plan_updated` payload.
+ *
+ * Accepts both `{steps}` at the root (what the runtime emits) and the nested
+ * `{plan:{steps}}` shape, so a payload written by either producer renders.
+ */
+export function readCopilotPlanPayload(payload) {
+    if (!payload || typeof payload !== "object")
+        return null;
+    const nested = payload.plan;
+    const rawSteps = (nested && typeof nested === "object" ? nested.steps : undefined) ??
+        payload.steps;
+    if (!Array.isArray(rawSteps))
+        return null;
+    const steps = [];
+    for (const raw of rawSteps) {
+        const step = readRawStep(raw);
+        if (step)
+            steps.push(step);
+    }
+    const summary = readText(payload.summary) ||
+        (nested && typeof nested === "object" ? readText(nested.summary) : "");
+    if (steps.length === 0 && summary.length === 0)
+        return null;
+    return { summary, steps };
+}
+/** Bookkeeping calls. Real work, but not work the USER asked for -- not substeps. */
+const BOOKKEEPING_TOOLS = new Set(["plan_update", "set_goal", "finish", "wait"]);
+/**
+ * One wild estimate must not be allowed to scale every remaining step.
+ *
+ * The calibration factor is a ratio of sums, so a single step the model guessed at
+ * 10s that actually took 10 minutes would otherwise multiply the whole tail by 60.
+ */
+const MIN_CALIBRATION = 0.25;
+const MAX_CALIBRATION = 4;
+const toMs = (value) => value instanceof Date ? value.getTime() : new Date(value).getTime();
+const toIso = (value) => value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+const normalizeTitleKey = (title) => title.replace(/\s+/g, " ").trim().toLowerCase();
+/**
+ * Rebuild the plan, with timings, from the session's event ledger.
+ *
+ * Returns null when the session has never published a plan -- which is the correct
+ * answer for a trivial turn, since the prompt tells the model to skip `plan_update`
+ * entirely and call `finish`. A rail that renders an empty shell for every greeting
+ * would be worse than one that stays away.
+ */
+export function projectCopilotPlan(input) {
+    const now = input.now ?? new Date();
+    const nowMs = now.getTime();
+    const events = [...input.events].sort((a, b) => a.seq - b.seq);
+    const planEvents = events.filter((event) => event.kind === "plan_updated");
+    if (planEvents.length === 0)
+        return null;
+    // -- Pass 1: fold the successive plans into one tracked set -----------------
+    //
+    // Identity is what makes timing possible. Match on `id` first, then on the
+    // normalised title. A step that matches NEITHER is genuinely new, and a payload
+    // in which nothing matches is a plan REPLACEMENT rather than an update -- which
+    // is exactly what session 4097ef0d's second plan_update was, having rewritten
+    // every description. Carrying timings across a rewrite would attribute one
+    // step's clock to an unrelated step; dropping them loses nothing real.
+    let tracked = [];
+    let summary = "";
+    let updatedAtSeq = planEvents[0]?.seq ?? 0;
+    let updatedAt = planEvents[0] ? toIso(planEvents[0].created_at) : now.toISOString();
+    for (const event of planEvents) {
+        const parsed = readCopilotPlanPayload(event.payload);
+        if (!parsed)
+            continue;
+        const atMs = toMs(event.created_at);
+        updatedAtSeq = event.seq;
+        updatedAt = toIso(event.created_at);
+        if (parsed.summary)
+            summary = parsed.summary;
+        if (parsed.steps.length === 0)
+            continue;
+        const byId = new Map(tracked.filter((t) => t.id).map((t) => [t.id, t]));
+        const byTitle = new Map(tracked.map((t) => [normalizeTitleKey(t.title), t]));
+        const next = [];
+        for (const [index, raw] of parsed.steps.entries()) {
+            const previous = (raw.id ? byId.get(raw.id) : undefined) ?? byTitle.get(normalizeTitleKey(raw.title));
+            const entry = previous ?? {
+                id: raw.id ?? `step-${index + 1}`,
+                title: raw.title,
+                status: raw.status,
+                estimateSeconds: raw.estimateSeconds,
+                startedAtMs: null,
+                endedAtMs: null,
+                modelSubsteps: [],
+                toolSubsteps: [],
+            };
+            entry.title = raw.title;
+            entry.status = raw.status;
+            // An estimate is a prior: keep the first one the model committed to rather
+            // than letting it be revised down to match reality after the fact.
+            if (entry.estimateSeconds === null)
+                entry.estimateSeconds = raw.estimateSeconds;
+            if (raw.substeps.length > 0)
+                entry.modelSubsteps = raw.substeps;
+            // The clock starts when the step is first SEEN in progress and stops when it
+            // is first seen finished. A step that appears already-done (no in-progress
+            // sighting) has no duration, and must not become a measurement sample.
+            if (raw.status === "in_progress" && entry.startedAtMs === null)
+                entry.startedAtMs = atMs;
+            if ((raw.status === "done" || raw.status === "blocked") && entry.endedAtMs === null) {
+                entry.endedAtMs = entry.startedAtMs === null ? null : atMs;
+            }
+            next.push(entry);
+        }
+        tracked = next;
+    }
+    if (tracked.length === 0)
+        return null;
+    // -- Pass 2: attribute observed tool calls to the step that was running -----
+    attributeToolCalls(events, planEvents, tracked, nowMs);
+    // -- Pass 3: the ETA --------------------------------------------------------
+    const samples = tracked
+        .filter((t) => t.status === "done" && t.startedAtMs !== null && t.endedAtMs !== null)
+        .map((t) => ({ step: t, seconds: (t.endedAtMs - t.startedAtMs) / 1000 }))
+        .filter((sample) => sample.seconds > 0);
+    const meanMeasured = samples.length > 0 ? samples.reduce((sum, s) => sum + s.seconds, 0) / samples.length : null;
+    const calibrationInputs = samples.filter((s) => s.step.estimateSeconds !== null);
+    let calibration = null;
+    if (calibrationInputs.length > 0) {
+        const measured = calibrationInputs.reduce((sum, s) => sum + s.seconds, 0);
+        const estimated = calibrationInputs.reduce((sum, s) => sum + (s.step.estimateSeconds ?? 0), 0);
+        if (estimated > 0) {
+            calibration = Math.min(Math.max(measured / estimated, MIN_CALIBRATION), MAX_CALIBRATION);
+        }
+    }
+    const steps = tracked.map((entry) => {
+        // Once a step has started it has an elapsed time: its own end if it finished,
+        // otherwise the clock. A step that never started has none -- which is exactly
+        // why it is also never a measurement sample.
+        const elapsedMs = entry.startedAtMs === null ? null : (entry.endedAtMs ?? nowMs) - entry.startedAtMs;
+        let etaSeconds = null;
+        let etaBasis = "none";
+        if (entry.status === "pending" || entry.status === "in_progress") {
+            let budget = null;
+            if (entry.estimateSeconds !== null && calibration !== null) {
+                budget = entry.estimateSeconds * calibration;
+                etaBasis = "calibrated";
+            }
+            else if (entry.estimateSeconds !== null) {
+                budget = entry.estimateSeconds;
+                etaBasis = "model";
+            }
+            else if (meanMeasured !== null) {
+                budget = meanMeasured;
+                etaBasis = "measured";
+            }
+            if (budget !== null) {
+                const spent = entry.status === "in_progress" && elapsedMs !== null ? elapsedMs / 1000 : 0;
+                etaSeconds = Math.max(Math.round(budget - spent), 0);
+            }
+        }
+        return {
+            id: entry.id,
+            title: entry.title,
+            status: entry.status,
+            estimateSeconds: entry.estimateSeconds,
+            startedAt: entry.startedAtMs === null ? null : new Date(entry.startedAtMs).toISOString(),
+            endedAt: entry.endedAtMs === null ? null : new Date(entry.endedAtMs).toISOString(),
+            elapsedMs,
+            etaSeconds,
+            etaBasis,
+            substeps: mergeSubsteps(entry),
+        };
+    });
+    const contributing = steps.filter((step) => (step.status === "pending" || step.status === "in_progress") && step.etaSeconds !== null);
+    let remainingSeconds = contributing.length > 0 ? contributing.reduce((sum, s) => sum + (s.etaSeconds ?? 0), 0) : null;
+    const overallBasis = remainingSeconds === null
+        ? "none"
+        : calibration !== null
+            ? "calibrated"
+            : meanMeasured !== null
+                ? "measured"
+                : "model";
+    // The turn cannot outlive its own deadline, so neither may the estimate. When
+    // the clamp binds, say so -- "4 minutes" and "4 minutes, but the turn is cut off
+    // in 90 seconds" are different facts and the second one is the useful one.
+    let deadlineBound = false;
+    if (remainingSeconds !== null && input.turnDeadlineAt) {
+        const deadlineLeft = (toMs(input.turnDeadlineAt) - nowMs) / 1000;
+        if (Number.isFinite(deadlineLeft) && deadlineLeft >= 0 && deadlineLeft < remainingSeconds) {
+            remainingSeconds = Math.round(deadlineLeft);
+            deadlineBound = true;
+        }
+    }
+    const done = steps.filter((step) => step.status === "done").length;
+    return {
+        summary: summary.length > 0 ? summary : null,
+        steps,
+        progress: { done, total: steps.length, ratio: steps.length === 0 ? 0 : done / steps.length },
+        eta: {
+            remainingSeconds,
+            basis: overallBasis,
+            measuredSteps: samples.length,
+            deadlineBound,
+        },
+        updatedAtSeq,
+        updatedAt,
+    };
+}
+/**
+ * Pair tool_call_started/finished on `call_id` and file each pair under whichever
+ * step was in progress when the call STARTED.
+ *
+ * Attribution uses the plan as of the call's own seq, not the final plan -- a call
+ * made during step 2 belongs to step 2 even after step 4 becomes current.
+ */
+function attributeToolCalls(events, planEvents, tracked, nowMs) {
+    const byId = new Map(tracked.map((t) => [t.id, t]));
+    const byTitle = new Map(tracked.map((t) => [normalizeTitleKey(t.title), t]));
+    /** Which tracked step was in progress at a given ledger position. */
+    const currentStepAt = (seq) => {
+        let current = null;
+        for (const planEvent of planEvents) {
+            if (planEvent.seq > seq)
+                break;
+            const parsed = readCopilotPlanPayload(planEvent.payload);
+            if (!parsed || parsed.steps.length === 0)
+                continue;
+            const inProgress = parsed.steps.find((step) => step.status === "in_progress");
+            if (!inProgress)
+                continue;
+            current =
+                (inProgress.id ? byId.get(inProgress.id) : undefined) ??
+                    byTitle.get(normalizeTitleKey(inProgress.title)) ??
+                    current;
+        }
+        return current;
+    };
+    const open = new Map();
+    // Sub-agent rollups arrive on a separate context_assembled event keyed by call_id.
+    const rollups = new Map();
+    for (const event of events) {
+        const payload = event.payload ?? {};
+        if (event.kind === "context_assembled" && payload.mode === "subagent") {
+            const callId = readText(payload.call_id);
+            if (callId) {
+                rollups.set(callId, {
+                    name: readText(payload.subagent) || "sub-agent",
+                    inferences: typeof payload.inferences === "number" ? payload.inferences : 0,
+                    capabilityCalls: typeof payload.capability_calls === "number" ? payload.capability_calls : 0,
+                });
+            }
+            continue;
+        }
+        if (event.kind !== "tool_call_started" && event.kind !== "tool_call_finished")
+            continue;
+        const callId = readText(payload.call_id);
+        const tool = readText(payload.tool);
+        if (!callId || BOOKKEEPING_TOOLS.has(tool))
+            continue;
+        const capability = readText(payload.capability) || tool || "capability";
+        if (event.kind === "tool_call_started") {
+            open.set(callId, {
+                step: currentStepAt(event.seq),
+                startedMs: toMs(event.created_at),
+                capability,
+                callId,
+            });
+            continue;
+        }
+        const started = open.get(callId);
+        open.delete(callId);
+        const target = started?.step ?? currentStepAt(event.seq);
+        if (!target)
+            continue;
+        const rollup = rollups.get(callId);
+        target.toolSubsteps.push({
+            id: callId,
+            // `summary` is the tool_call_finished remap the Copilot host writes; it is a
+            // line ("63 columns"), which is what a substep wants. Fall back to the
+            // capability name rather than to a serialized result.
+            title: readText(payload.summary) || capability,
+            status: payload.ok === false ? "blocked" : "done",
+            source: "tool",
+            durationMs: started ? toMs(event.created_at) - started.startedMs : null,
+            startedAt: started ? new Date(started.startedMs).toISOString() : null,
+            ...(rollup ? { subagent: rollup } : {}),
+        });
+    }
+    // A call still open at the end of the ledger is genuinely running right now.
+    for (const [callId, entry] of open) {
+        if (!entry.step)
+            continue;
+        entry.step.toolSubsteps.push({
+            id: callId,
+            title: entry.capability,
+            status: "in_progress",
+            source: "tool",
+            durationMs: nowMs - entry.startedMs,
+            startedAt: new Date(entry.startedMs).toISOString(),
+        });
+    }
+}
+/**
+ * Model-declared substeps first, then the observed calls.
+ *
+ * Both are kept because they answer different questions: the model's substeps say
+ * what it MEANT to do, the tool calls say what it actually did. Showing only the
+ * first trusts a field the model frequently omits; showing only the second reduces
+ * a plan to a call log.
+ */
+function mergeSubsteps(entry) {
+    const declared = entry.modelSubsteps.map((sub, index) => ({
+        id: sub.id ?? `${entry.id}-sub-${index + 1}`,
+        title: sub.title,
+        status: sub.status,
+        source: "model",
+        durationMs: null,
+        startedAt: null,
+    }));
+    return [...declared, ...entry.toolSubsteps];
+}

package/node_modules/@oxygen/shared/dist/dnc-identities.d.ts

@@ -18,6 +18,16 @@ export type DncIdentityInput = {
     detail?: string;
     metadata?: Record<string, unknown>;
 };
+/** Durable subject metadata shared by independently enforced DNC ledgers. */
+export declare const DNC_SUBJECT_KINDS: readonly ["person", "company"];
+export type DncSubjectKind = (typeof DNC_SUBJECT_KINDS)[number];
+export type DncSubject = {
+    id: string;
+    kind: DncSubjectKind;
+    name: string | null;
+};
+export declare function dncSubjectMetadata(subject: DncSubject): Record<string, unknown>;
+export declare function readDncSubject(metadata: unknown): DncSubject | null;
 export type CompanyDncIdentity = {
     kind: "domain" | "linkedin_company";
     value: string;

package/node_modules/@oxygen/shared/dist/dnc-identities.js

@@ -17,6 +17,29 @@ export const DNC_IDENTITY_KINDS = [
     "company_domain",
     "linkedin_company",
 ];
+/** Durable subject metadata shared by independently enforced DNC ledgers. */
+export const DNC_SUBJECT_KINDS = ["person", "company"];
+export function dncSubjectMetadata(subject) {
+    return {
+        dnc_subject_id: subject.id,
+        dnc_subject_kind: subject.kind,
+        ...(subject.name ? { dnc_subject_name: subject.name } : {}),
+    };
+}
+export function readDncSubject(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+        return null;
+    const record = metadata;
+    const id = readNonEmptyString(record.dnc_subject_id);
+    const kind = readNonEmptyString(record.dnc_subject_kind);
+    if (!id || !DNC_SUBJECT_KINDS.includes(kind))
+        return null;
+    return {
+        id,
+        kind: kind,
+        name: readNonEmptyString(record.dnc_subject_name),
+    };
+}
 const E164_PATTERN = /^\+[1-9]\d{1,14}$/;
 const DOMAIN_PATTERN = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const COMPANY_DOMAIN_ROW_KEYS = [

package/node_modules/@oxygen/shared/dist/egress-transport-readiness.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared/dedicated send-drain handoff timing. The worker and every status
+ * surface must evaluate the same readiness envelope: inventory existence alone
+ * is not proof that a dedicated process may claim sends yet.
+ */
+/** Longest a process may reuse one control-plane scope snapshot. */
+export declare const EGRESS_SEND_SCOPE_CACHE_MAX_AGE_MS = 60000;
+/** Longest a tenant cycle may start provider sends under that snapshot. */
+export declare const EGRESS_SEND_AUTHORITY_RETENTION_MS = 45000;
+/** Clock/scheduling margin between the old authority expiring and the new one starting. */
+export declare const EGRESS_SEND_HANDOFF_MARGIN_MS = 5000;
+/**
+ * No new drain may become authoritative until every old cached scope AND every
+ * send cycle started on that cache's final millisecond have expired.
+ */
+export declare const DEDICATED_EGRESS_HANDOFF_DELAY_MS: number;
+export declare const DEDICATED_EGRESS_LIVENESS_MAX_AGE_MS: number;
+export type DedicatedEgressTransportReadiness = {
+    ready: true;
+} | {
+    ready: false;
+    reason: "handoff_pending" | "vendor_verification_missing_or_stale";
+};
+export type FlyDedicatedEgressTransportReadiness = {
+    ready: true;
+    appName: string;
+} | {
+    ready: false;
+    reason: "dedicated_app_identity_missing" | "handoff_pending" | "vendor_verification_missing_or_stale";
+};
+export declare function evaluateDedicatedEgressTransportReadiness(input: {
+    createdAt: Date | null;
+    vendorVerifiedAt: Date | null;
+}, now?: number): DedicatedEgressTransportReadiness;
+/**
+ * The app name Fly assigns to this inventory row, or null when the row cannot
+ * authorize any dedicated process. Automated Fly purchase stores the app name
+ * as metadata.vendor_order_id because one app is exactly one vendor lease.
+ */
+export declare function readFlyDedicatedEgressAppName(input: {
+    environment: "dev" | "prod";
+    metadata: Record<string, unknown> | null;
+}): string | null;
+/**
+ * Fly-specific readiness shared by the drain, status, and purchase replay.
+ * Timestamps cannot authorize an app by themselves: an orphan process for the
+ * same org must match the exact active row's immutable Fly app identity.
+ */
+export declare function evaluateFlyDedicatedEgressTransportReadiness(input: {
+    createdAt: Date | null;
+    vendorVerifiedAt: Date | null;
+    environment: "dev" | "prod";
+    metadata: Record<string, unknown> | null;
+}, now?: number): FlyDedicatedEgressTransportReadiness;
+/**
+ * Retiring a drain is the inverse handoff: shared must remain excluded until
+ * every process that could have cached dedicated authority has expired it.
+ * Writers stamp this field with DB time while preserving the rest of metadata.
+ */
+export declare function dedicatedEgressRetirementStillCooling(metadata: Record<string, unknown> | null, now?: number): boolean;