@opencxh/domain 1.274.0 → 1.276.0

package/dist/entities/activity/types.d.ts

@@ -281,7 +281,7 @@ export type AIActionProposedPayload = {
     runId: string;
     playbookId?: string;
     playbookName?: string;
-    /** The held actions, e.g. { action: "tool:mcp__jira__create_issue", params }. */
+    /** The held actions, e.g. { action: "mcp__jira__create_issue", params }. */
     actions: {
         action: string;
         params?: Record<string, unknown>;
@@ -289,6 +289,10 @@ export type AIActionProposedPayload = {
     status: "pending" | "approved" | "rejected";
     /** Who the proposal was made on behalf of, so the card can show "on behalf of Finance". */
     actor?: ActingIdentity;
+    /** The approval request that decides it — the card decides through that, not through ai. */
+    approvalRequestId?: string;
+    /** Every request this proposal waits on, one per guarded act; the first is `approvalRequestId`. */
+    approvalRequestIds?: string[];
 };
 /** Playbook lifecycle marker in the interaction timeline (system-authored). */
 export type PlaybookLifecyclePayload = {

package/dist/entities/ai-account/capabilities.d.ts

@@ -38,6 +38,10 @@ export declare const AI_CAPABILITIES: readonly [{
     readonly id: "embedding";
     readonly defaultFlag: "isDefaultEmbedding";
     readonly label: "Embeddings";
+}, {
+    readonly id: "decision";
+    readonly defaultFlag: "isDefaultDecision";
+    readonly label: "Beslissingen";
 }];
 /** What an account can be the default for, and what a vendor can claim. One vocabulary. */
 export type AiCapability = (typeof AI_CAPABILITIES)[number]["id"];

package/dist/entities/ai-account/index.d.ts

@@ -1,3 +1,6 @@
 export * from './capabilities';
+export * from './modality';
+export * from './routing';
+export * from './system-one';
 export * from './types';
 export * from './vendors';

package/dist/entities/ai-account/modality.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What one **model** can take in and give back.
+ *
+ * The question used to be asked per *vendor* (`aiVendorAcceptsAttachment`), and that is wrong in
+ * both directions: within one vendor models differ — a small fast model and its flagship do not
+ * read the same things — and it covered input only, so `tts` stayed an account flag with a form
+ * and no adapter behind it.
+ *
+ * The vocabulary is the source's, not ours (`architecture.input_modalities` on OpenRouter), and
+ * deliberately so: it is synced hourly and a translation table here would be a second place to
+ * maintain the same fact. That is why these are plain strings.
+ */
+export interface ModelModality {
+    in: string[];
+    out: string[];
+}
+/**
+ * Does this model accept this kind — or is it simply not in the catalog?
+ *
+ * **Three states, on purpose.** `undefined` means "the catalog does not know this model", which a
+ * caller must be able to tell from a "no": the answer then falls back to what the vendor
+ * declares, rather than silently refusing every attachment on a self-hosted or brand-new model.
+ */
+export declare function modelAcceptsAttachment(modality: ModelModality | undefined, kind: string): boolean | undefined;

package/dist/entities/ai-account/modality.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/ai-account/routing.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Which model answers this turn — decided per request instead of once per profile.
+ *
+ * Today nobody chooses: the model stands on the profile, or it is the account's default. Every
+ * question gets the same brain, whether it is *"mark this conversation resolved"* or *"write the
+ * quote letter"*. That is slow on the cheap questions and expensive on all of them.
+ *
+ * The routing rules are **rules**, not a model: the shape of a request is known without asking
+ * anyone. A hop to a classifier here would cost ~100 ms and a call to decide something that is
+ * free to decide.
+ */
+export declare const MODEL_TIERS: readonly ["fast", "standard", "deep"];
+export type ModelTier = (typeof MODEL_TIERS)[number];
+/** Which account and model answer at one level. Both, because a tier can live on another vendor. */
+export interface TierBinding {
+    accountId: string;
+    model: string;
+}
+export type ModelTiers = Partial<Record<ModelTier, TierBinding>>;
+/**
+ * What this turn looks like, in the things that are knowable **before** the model is asked.
+ *
+ * Deliberately no context size, though the plan names it. The size is only known after the turn
+ * is assembled, and the assembly needs the provider, which needs the account, which is what this
+ * decides. The rule it would serve (a small classify goes to `fast`) is carried by
+ * {@link RoutingRequest.expectsSchema}, and that is the case it was written for.
+ */
+export interface RoutingRequest {
+    /** `ask` reads, `draft` prepares, `agent` may act. Absent counts as `agent`. */
+    mode?: string;
+    /** How many tools the profile puts on the table. Zero is the cheap case. */
+    toolCount?: number;
+    hasAttachments?: boolean;
+    /** A structured answer against a schema: classify, extract, judge. */
+    expectsSchema?: boolean;
+    /** This turn repairs a failed one. Measured, not guessed — see the control-repair trace. */
+    repair?: boolean;
+    /** The ceiling the role allows. A cap, never a per-turn choice. */
+    maxTier?: ModelTier;
+    /** `soft` = a budget passed its warning threshold. `hard` never reaches here; it refuses. */
+    budgetPressure?: "none" | "soft";
+}
+export interface RoutingDecision {
+    tier: ModelTier;
+    /** Why, in the order the rules fired. Lands in the run so a bill can be read back. */
+    reasons: string[];
+}
+/**
+ * The tier for one request.
+ *
+ * Order matters and is the whole design: pick a base from the shape, escalate a repair, then
+ * **degrade under budget pressure rather than refuse**, and finally clamp to whatever ceiling the
+ * role set. Degrading last-but-one is deliberate — a cheaper answer is nearly always better than
+ * no answer, and today a full budget is a closed door.
+ */
+export declare function resolveTier(request: RoutingRequest): RoutingDecision;
+export interface Route extends RoutingDecision {
+    accountId: string;
+    model: string;
+    /** False when no tier was bound and the profile's own choice stands. */
+    routed: boolean;
+}
+/**
+ * The tier, resolved to an account and a model.
+ *
+ * **An unconfigured organisation must change nothing.** Tiers are opt-in, so an empty map means
+ * the profile's own account and model answer exactly as they did — which is also why the walk
+ * downward exists: a half-filled ladder (`fast` and `deep`, nothing between) should still route
+ * rather than fall back to the profile and quietly ignore what was configured.
+ */
+export declare function resolveRoute(tiers: ModelTiers | undefined, request: RoutingRequest, fallback: TierBinding): Route;

package/dist/entities/ai-account/routing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/ai-account/system-one.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The System One contract: ask a model a **question about a state**, get a number back.
+ *
+ * A different shape of model from every other one in this platform. A chat model is handed a
+ * prompt and writes text; this one is handed a state plus a set of typed questions and answers
+ * each of them as a probability distribution. It generates nothing — the docs say so outright —
+ * which is exactly why it is worth having: *"does this answer the question?"* is a yes/no with a
+ * degree, and a chat model asked that writes a paragraph about it.
+ *
+ * **Questions come as a set, and that is the contract rather than an optimisation.** Measured by
+ * the vendor: thirteen questions in one call against a 54k-character document were 12.2× cheaper
+ * and 10× faster than thirteen calls, and each question is scored on its own — batching adds no
+ * cross-talk. Anything that asks one question at a time here is paying twelve times over.
+ */
+/** What a `true` and a `false` mean for this question. Optional; the instructions usually say it. */
+export interface NoulCriteria {
+    true?: string;
+    false?: string;
+}
+export interface NoulQuestion {
+    type: "noul";
+    instructions: string;
+    criteria?: NoulCriteria;
+}
+/** Options as `{ name: description }`. A `null` description means "the name says it". */
+export interface ChoiceQuestion {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string | null>;
+}
+/** An ordered rubric, lowest first. */
+export interface ScoreQuestion {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+}
+export type SystemOneQuestion = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+/**
+ * P(yes), 0..1 — the answer and the certainty in one number.
+ *
+ * **No separate `confidence`, and that is deliberate on the vendor's side**: a yes/no has two
+ * outcomes, so one number describes the whole distribution. 0.5 is not "unsure about yes", it is
+ * "yes and no weighed the same".
+ */
+export interface NoulAnswer {
+    type: "noul";
+    noul: number;
+}
+export interface ChoiceAnswer {
+    type: "choice";
+    choice: string;
+    confidence: number;
+    probabilities: Record<string, number>;
+}
+export interface ScoreAnswer {
+    type: "score";
+    score: number;
+    confidence: number;
+    legend?: Record<string, string>;
+    probabilities?: Record<string, number>;
+}
+export type SystemOneAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+export interface SystemOneRequest {
+    /** The thing being judged. A string, or a labelled object — the labels are read. */
+    state: unknown;
+    model?: string;
+    questions: Record<string, SystemOneQuestion>;
+}
+export interface SystemOneResponse {
+    model: string;
+    answers: Record<string, SystemOneAnswer>;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+    };
+}
+/** Vendor limits, so a request is refused here rather than as a 422 nobody reads. */
+export declare const MAX_CHOICE_OPTIONS = 255;
+export declare const MIN_SCORE_LEVELS = 2;
+export declare const MAX_SCORE_LEVELS = 10;
+/**
+ * What is wrong with this question set, or `null`.
+ *
+ * Checked before the call because the alternative is a 422 with a vendor's wording in a log, and
+ * because these are the mistakes a caller makes while writing a question rather than at runtime.
+ */
+export declare function validateQuestions(questions: Record<string, SystemOneQuestion>): string | null;
+export type DecisionBand = "act" | "check" | "refuse";
+/**
+ * What to *do* with a number, in three bands.
+ *
+ * The vendor is explicit that the thresholds are domain-specific and that you should start
+ * conservatively — so they are parameters, not constants, and the default is deliberately timid.
+ * The three bands are the vendor's own architecture advice: act, act-but-confirm, do not act.
+ *
+ * **`check` is the honest middle and must not be collapsed.** Two bands force every uncertain
+ * answer into either a silent action or a dead end; the middle is where a human gets asked, which
+ * is the entire reason a calibrated number is worth more than a label.
+ */
+export declare function decisionBand(value: number, act?: number, check?: number): DecisionBand;
+/**
+ * Questions this model should not be asked.
+ *
+ * Straight from the vendor's own jaggedness page, and worth having in code rather than in a
+ * doc: counting, arithmetic, raw numeric values and **dates** are named failure modes — it
+ * "reads dates as text, not as ordered quantities". Every one of those has a deterministic
+ * answer in this codebase already, so asking a model is both worse and more expensive.
+ */
+export declare const SYSTEM_ONE_NON_GOALS: readonly ["counting or arithmetic", "comparing dates or durations", "judging whether two numbers are close", "generating text"];

package/dist/entities/ai-account/system-one.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/ai-account/types.d.ts

@@ -1,4 +1,5 @@
-export interface AiAccount {
+import { AiDefaultFlags } from './capabilities';
+interface AiAccountFields {
     id: string;
     organizationId: string;
     vendor: string;
@@ -9,8 +10,14 @@ export interface AiAccount {
      * is ignored.
      */
     baseUrl?: string;
-    isDefaultLlm?: boolean;
-    isDefaultStt?: boolean;
-    isDefaultTts?: boolean;
-    isDefaultEmbedding?: boolean;
 }
+/**
+ * The default flags, **derived** from the capability catalog rather than listed again.
+ *
+ * They were written out by hand here, which is the drift the catalog exists to stop: adding
+ * `decision` gave every other place a fifth checkbox and this interface a fourth, so the form
+ * offered a flag the type did not have. One list, everything else follows.
+ */
+export interface AiAccount extends AiAccountFields, Partial<AiDefaultFlags> {
+}
+export {};

package/dist/entities/ai-account/vendors.d.ts

@@ -1,14 +1,9 @@
 import { AiCapability } from './capabilities';
-/**
- * What a vendor can do. Was its own union of three; it is the same vocabulary the account
- * defaults and the usage rows use, so it now names {@link AiCapability} instead of repeating it.
- */
-export type AiVendorCapability = AiCapability;
 export interface AiVendor {
     id: string;
     label: string;
     /** What this vendor can do. Decides where it appears as an option in the UI. */
-    capabilities: readonly AiVendorCapability[];
+    capabilities: readonly AiCapability[];
     /** Model a call runs on when it carries none itself. Absent for vendors without a chat adapter. */
     defaultModel?: string;
     /**
@@ -38,7 +33,7 @@ export declare function aiVendorLabel(vendorId: string): string;
  */
 export declare function aiVendorDefaultModel(vendorId: string, fallback?: string): string;
 /** Vendors offering this capability — for capability-filtered pickers. */
-export declare function aiVendorsWith(capability: AiVendorCapability): AiVendor[];
+export declare function aiVendorsWith(capability: AiCapability): AiVendor[];
 /** True when the user has to fill in a host themselves (the vendor has no fixed one). */
 export declare function aiVendorNeedsBaseUrl(vendorId: string): boolean;
 /** Does this vendor accept this attachment kind? Text always works — that is prompt. */

package/dist/entities/ai-message/types.d.ts

@@ -39,6 +39,8 @@ export interface AIMessageOutput {
  * question and then having the same thread draft a reply is the normal flow.
  */
 export type AssistantMode = "ask" | "draft" | "agent";
+/** Is this one of the three modes? For request bodies, which may carry anything. */
+export declare function isAssistantMode(value: unknown): value is AssistantMode;
 export interface AIMessage {
     id: string;
     organizationId: string;
@@ -97,6 +99,13 @@ export interface AIMessage {
     toolsTotal?: number;
     /** Which mode this turn ran as. Absent = `"agent"`: every row written before modes existed. */
     mode?: AssistantMode;
+    /**
+     * Why this model answered — one line per routing rule that fired.
+     *
+     * Absent when nothing was routed, which is every organisation that bound no tiers. A reason for
+     * a choice nobody made would read as a decision.
+     */
+    routing?: string[];
 }
 export type AIMessageFeedback = "up" | "down";
 /**

package/dist/entities/ai-settings/types.d.ts

@@ -1,3 +1,4 @@
+import { ModelTiers } from '../ai-account/routing';
 /**
  * What an organisation configures for the AI app as a whole — not per profile, not per user.
  *
@@ -5,6 +6,14 @@
  * setting nobody can find.
  */
 export interface AiOrgSettings {
+    /**
+     * Which account and model answer at `fast`, `standard` and `deep`.
+     *
+     * **Opt-in and empty by default.** An organisation that configures nothing keeps exactly what
+     * it has: the profile's own model answers every turn. Only once a tier is bound does the router
+     * (`resolveRoute`) get anything to choose between.
+     */
+    tiers?: ModelTiers;
     /**
      * May the AI app listen in on conversations (speech to text)?
      *

package/dist/entities/approval/decide-each.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Give one verdict on every request of a proposal that this person may decide.
+ *
+ * A park asks one request per guarded act, each with its own approvers; the person pressing the
+ * button signs the ones that are theirs. A request that is not theirs (403) or already settled
+ * (400) is counted as `waiting` rather than failing the rest — anything else is a real error.
+ */
+export declare function decideEach(requestIds: readonly string[], decideOne: (requestId: string) => Promise<unknown>): Promise<{
+    decided: number;
+    waiting: number;
+}>;
+/** The requests a proposal waits on, from the list or the single id older rows carry. */
+export declare function proposalRequestIds(source: {
+    approvalRequestIds?: readonly string[] | null;
+    approvalRequestId?: string | null;
+}): string[];

package/dist/entities/approval/decide-each.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/approval/index.d.ts

@@ -1,2 +1,3 @@
+export * from './decide-each';
 export * from './policy';
 export * from './types';

package/dist/entities/eval/index.d.ts

@@ -0,0 +1,2 @@
+export * from './runner';
+export * from './types';

package/dist/entities/eval/runner.d.ts

@@ -0,0 +1,14 @@
+import { EvalCase, EvalCaseResult, EvalRun } from './types';
+/**
+ * Run a suite. The judge is injected, which is the whole reason this is one function.
+ *
+ * A deterministic suite (rule correctness, a classification against a known answer) judges by
+ * comparison and costs nothing; a judged suite asks a model. Both are the same loop, and keeping
+ * that loop in one place is what makes "put this in CI" a decision about the judge rather than a
+ * second implementation.
+ *
+ * **Sequential, not parallel.** A judged suite is a batch of model calls, and firing forty at
+ * once is how a rate limit turns a measurement into a red build. A deterministic judge is fast
+ * enough that the difference does not register.
+ */
+export declare function runEvalSuite<I, E>(suite: string, target: string, cases: readonly EvalCase<I, E>[], judge: (testCase: EvalCase<I, E>) => Promise<EvalCaseResult> | EvalCaseResult, now?: number): Promise<EvalRun>;

package/dist/entities/eval/runner.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/eval/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Measuring whether this platform is any good at the things it decides.
+ *
+ * Today that exists once, as a test file inside the playbook folder: a handful of cases, opt-in,
+ * never in CI. That is not small-but-good, it is the wrong shape — it measures one kind of thing
+ * (a playbook prompt) while seven things need exactly the same machinery: prompt quality, the
+ * accuracy of a classification, **rule correctness**, retrieval, tool selection, whether an agent
+ * turn reached its control move, and live answer quality.
+ *
+ * Two design rules live in the shape itself. A case carries either an `expected` value **or** a
+ * `rubric`, because those are the two ways anything here can be judged: exactly, or by opinion —
+ * and an opinion needs a judge, which costs money and has to be calibrated. And a case is
+ * something you can *harvest*: every correction in the feedback loop is by definition a labelled
+ * case, while a golden set written by hand is out of date within a quarter.
+ */
+export interface EvalCase<Input = unknown, Expected = unknown> {
+    id: string;
+    /** What kind of thing is judged: `rule`, `classify`, `retrieval`, `tool-selection`, … */
+    subject: string;
+    input: Input;
+    /** The exact answer, when there is one. Mutually exclusive with {@link EvalCase.rubric}. */
+    expected?: Expected;
+    /** What "good" means, for a case only a judge can settle. */
+    rubric?: string;
+    tags?: string[];
+}
+export interface EvalCaseResult {
+    caseId: string;
+    ok: boolean;
+    /** What actually happened, in the case's own terms. Present on a failure; optional otherwise. */
+    got?: unknown;
+    /** Why it failed, in a sentence a person can act on. */
+    note?: string;
+}
+export interface EvalRun {
+    suite: string;
+    /** What was measured: a model id, a rule set version, a prompt. */
+    target: string;
+    at: number;
+    /** Passed over total, 0..1. `1` on an empty suite — nothing failed. */
+    score: number;
+    perCase: EvalCaseResult[];
+}
+export declare function summariseEval(suite: string, target: string, perCase: readonly EvalCaseResult[], at?: number): EvalRun;
+/** The failures, as lines. What a CI log should print and nothing more. */
+export declare function failureLines(run: EvalRun): string[];

package/dist/entities/inbox/types.d.ts

@@ -11,10 +11,10 @@ export interface Inbox {
     /**
      * Hours a first reply may take in this inbox before a conversation counts as at risk.
      *
-     * Absent = the ladder per priority ({@link SLA_HOURS_BY_PRIORITY}), which is what every
-     * organisation silently ran on: the onboarding step promised a norm per inbox, ticked itself
-     * off on `ticketEnabled`, and nothing anywhere stored an agreed number. So the Focus badge and
-     * Assist' SLA nudge were a hardcoded opinion.
+     * **Absent = no service target at all**, not a default. A ladder per priority used to stand in
+     * (1/4/8/24) and that was a hardcoded opinion: every inbox, and every conversation outside one,
+     * silently carried a promise nobody made. Deliberately not being in an SLA — personal mail —
+     * is the common case, so it is the one that needs no configuration.
      *
      * One number and not four (one per priority): an inbox usually *is* the agreement ("support:
      * within 4 hours"), and four fields per inbox is four things to keep consistent while the

package/dist/entities/interaction/attention.d.ts

@@ -1,4 +1,4 @@
-import { AttentionCtx, ParkMark, Priority, Scored } from '../../platform/attention';
+import { AttentionCtx, ParkMark, Scored } from '../../platform/attention';
 import { Interaction } from './types';
 /** The only statuses that can ask for attention; `closed` and `snoozed` never compete. */
 export declare const ATTENTION_STATUSES: readonly ["open"];
@@ -15,11 +15,6 @@ export declare const ATTENTION_STATUSES: readonly ["open"];
  * larger than any positive contribution, so bulk always ranks below every real conversation.
  */
 export declare const BULK_PENALTY = 1000;
-/**
- * Hours a first response is "allowed" per priority before an open interaction counts as
- * SLA-at-risk. Also consumed by the Mijn dag KPI and the wait heuristic.
- */
-export declare const SLA_HOURS_BY_PRIORITY: Record<Priority, number>;
 /**
  * How long you wait for a reply before the conversation asks for attention again. Without this
  * bound a thread the customer never replied to would stay out of sight forever.
@@ -48,16 +43,17 @@ export declare function isReminderActive(reminder: ParkMark | undefined, i: Inte
 /** Whole hours an open interaction has been waiting (never negative). */
 export declare function waitHoursOf(i: Interaction, now: number): number;
 /**
- * The first-reply budget for this conversation, in hours.
+ * The first-reply budget for this conversation in hours, or `undefined` when nobody agreed one.
  *
- * The inbox's own norm wins when it has one; otherwise the ladder per priority. One helper
- * rather than the lookup at each call site, because three readers ask this question (the Focus
- * badge, "Mijn dag", and Assist' nudge tag) and a fourth answer would be a fourth opinion.
+ * **There is deliberately no fallback.** A ladder per priority used to fill this in (1/4/8/24),
+ * which invented an agreement nobody made: a personal mailbox got an eight-hour promise for the
+ * sole reason that its priority was unset. "No service target" is a valid state — most mail is
+ * in it — and it has to look different from a target someone actually configured.
  *
  * A non-positive stored value is treated as absent: "0 hours" is not an agreement, it is an
  * empty field that made it through a form.
  */
-export declare function slaHoursFor(i: Interaction, slaByInbox?: Record<string, number>): number;
+export declare function slaHoursFor(i: Interaction, slaByInbox?: Record<string, number>): number | undefined;
 /**
  * Index inboxes the way {@link slaHoursFor} wants them: only the ones that named a norm.
  *
@@ -71,8 +67,11 @@ export declare function slaHoursByInbox(inboxes: readonly {
 /**
  * True when an open interaction has waited past its first-reply budget.
  *
- * `slaByInbox` maps inbox id -> agreed hours; a caller that has no inboxes at hand may leave it
- * out and gets the priority ladder, which is exactly the old behaviour.
+ * No budget, no risk. A conversation in an inbox that named no norm cannot be late, because
+ * there is nothing to be late for — so the answer is `false`, not "unknown". The one reader is a
+ * badge, and a badge that fires on an agreement that does not exist is the bug this removed.
+ *
+ * `slaByInbox` maps inbox id -> agreed hours; leave it out and nothing is ever at risk.
  */
 export declare function isSlaAtRisk(i: Interaction, now: number, slaByInbox?: Record<string, number>): boolean;
 /**

package/dist/entities/kb/index.d.ts

@@ -1,4 +1,5 @@
 export * from './help-center';
+export * from './keys';
 export * from './locales';
 export * from './tree';
 export * from './types';

package/dist/entities/kb/keys.d.ts

@@ -0,0 +1,2 @@
+/** The scope kind of one article: `article:<id>`. One definition for the claim and the owner. */
+export declare const ARTICLE_SCOPE_KIND = "article";

package/dist/entities/playbook/actor.d.ts

@@ -1,20 +1,9 @@
 import { ActingIdentity } from '../../platform/identity';
-import { toActingIdentity } from '../scope/actor';
 import { OwnerScope } from '../scope/types';
-/**
- * `ownerScope` **is** a playbook's actor: there is no separate `runAs` field. Visibility, working
- * area and attribution therefore all follow from the same field.
- *
- * On the storage side the personal variant is called `personal` (as with every other entity), on
- * the execution side `user` (as with every other acting identity). This function is that
- * translation, and the only place it belongs.
- */
-export declare const playbookActor: typeof toActingIdentity;
 /**
  * Who this run acts for.
  *
- * **Two different questions, and the whole reason this function exists next to
- * {@link playbookActor}:**
+ * **Two different questions**, which is why this is not just `toActingIdentity(ownerScope)`:
  *
  * - *who acts* — the agent, when one is designated;
  * - *who may manage this* — `ownerScope`, and that stays with humans.

package/dist/entities/playbook/approval.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A parked run's address in the approval layer: `playbook-run:<runId>~<step>`.
+ *
+ * The park is part of the key on purpose. The approval layer de-duplicates on `(scopeKey, act)`
+ * and keeps one approved row per key, so a flow that parks, resumes and parks again on a later
+ * step needs a key per park — while a retry of the *same* park must find its open request.
+ * `~` because the key travels in paths too, where `/` and `.` already mean something.
+ */
+export declare const PLAYBOOK_RUN_SCOPE_KIND = "playbook-run";
+/** The one act a parked run asks for: "carry out what was proposed". */
+export declare const PLAYBOOK_RUN_APPROVAL_ACT = "run";
+export declare function runApprovalKey(runId: string, step?: number): string;
+/** The run behind an approval key's ref (`<runId>~<step>`), or the ref itself without a step. */
+export declare function runIdOfApprovalRef(ref: string): string;

package/dist/entities/playbook/approval.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/playbook/autonomy.d.ts

@@ -0,0 +1,25 @@
+import { Autonomy } from './types';
+/** Is this one of the three settings? For request bodies, which may carry anything. */
+export declare function isAutonomy(value: unknown): value is Autonomy;
+/**
+ * How much a run may do on its own, decided **once** at its start and frozen on the run. The
+ * playbook's setting wins where there is one (that is where the organisation configured it), then
+ * the agent's, then `suggest`.
+ *
+ * `demoted`: several autonomous playbooks would act outward on the same subject at once. They
+ * keep doing internal work themselves; a human decides which one goes out.
+ */
+export declare function resolveAutonomy(input: {
+    playbook?: {
+        autonomy?: Autonomy;
+    } | null;
+    agent?: {
+        autonomy?: Autonomy;
+    } | null;
+    demoted?: boolean;
+}): Autonomy;
+/**
+ * A step's own setting may make it more careful than its run, never less: the run's value is
+ * where a demotion and the agent's mandate already landed.
+ */
+export declare function narrowAutonomy(run: Autonomy | undefined, step: Autonomy | undefined): Autonomy;

package/dist/entities/playbook/autonomy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/playbook/index.d.ts

@@ -1,5 +1,7 @@
 export * from './actor';
+export * from './approval';
 export * from './assignment';
+export * from './autonomy';
 export * from './labels';
 export * from './trigger-vars';
 export * from './types';

package/dist/entities/playbook/labels.d.ts

@@ -1,5 +1,5 @@
 /**
- * Readable name of an action/tool for a human: `tool:communication__update_interaction` becomes
+ * Readable name of an action/tool for a human: `communication__update_interaction` becomes
  * `communication · update interaction`.
  *
  * Shared, because the proposal card in comms already had this helper while the run timeline in the
@@ -7,8 +7,6 @@
  * `voorstel: tool:mcp__jira__create_issue`.
  */
 export declare function humanizeAction(action: string): string;
-/** The namespaced tool id without the step's `tool:` prefix. */
-export declare function toolName(action: string): string;
 /**
  * The tool's own name, without the namespace that says who owns it:
  * `work__create_work_item` and `mcp__jira__create_issue` become `create_work_item` and