@things-factory/ai-assistant 10.1.203 → 10.1.205

package/dist-server/service/unattended-run/run-as.js

@@ -0,0 +1,26 @@
+"use strict";
+/*
+ * Who the run is - judged again at every run (design/ai/unattended-run.md §2, ADR-0142 §8.1).
+ *
+ * The run acts for the policy owner and for no one else. There is no second user to fall back to: a refused owner
+ * means a refused run, never one under an administrator.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASK_ASSISTANT_GATE = void 0;
+exports.judgeRunAs = judgeRunAs;
+/** The same door a person passes to ask the assistant (`assistantChat`). */
+exports.ASK_ASSISTANT_GATE = { category: 'ai-assistant', privilege: 'mutation', owner: true };
+/** `user` is the account as `findUser` read it just now - absent when there is none. */
+async function judgeRunAs(user, domain, checks) {
+    if (!user)
+        return { refused: 'assistant-run-as-unknown' };
+    /* Only an account that can sign in now. Locked, banned, deleted, or one waiting for a password reset is not. */
+    if (user.status !== 'activated')
+        return { refused: 'assistant-run-as-inactive' };
+    if (!(await checks.mayCheckin(user, domain)))
+        return { refused: 'assistant-run-as-not-member' };
+    if (!(await checks.permits(exports.ASK_ASSISTANT_GATE, user, domain)))
+        return { refused: 'assistant-run-as-not-permitted' };
+    return { user };
+}
+//# sourceMappingURL=run-as.js.map

package/dist-server/service/unattended-run/run-as.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-as.js","sourceRoot":"","sources":["../../../server/service/unattended-run/run-as.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAqBH,gCAWC;AA9BD,4EAA4E;AAC/D,QAAA,kBAAkB,GAAG,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AAiBlG,wFAAwF;AACjF,KAAK,UAAU,UAAU,CAC9B,IAA8B,EAC9B,MAAe,EACf,MAAqD;IAErD,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAA;IACzD,gHAAgH;IAChH,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,EAAE,OAAO,EAAE,2BAA2B,EAAE,CAAA;IAChF,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,6BAA6B,EAAE,CAAA;IAC/F,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,OAAO,CAAC,0BAAkB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAA;IACnH,OAAO,EAAE,IAAI,EAAE,CAAA;AACjB,CAAC","sourcesContent":["/*\n * Who the run is - judged again at every run (design/ai/unattended-run.md §2, ADR-0142 §8.1).\n *\n * The run acts for the policy owner and for no one else. There is no second user to fall back to: a refused owner\n * means a refused run, never one under an administrator.\n */\n\n/** The same door a person passes to ask the assistant (`assistantChat`). */\nexport const ASK_ASSISTANT_GATE = { category: 'ai-assistant', privilege: 'mutation', owner: true }\n\nexport type RunAsRefusal =\n  | 'assistant-run-as-unknown'\n  | 'assistant-run-as-inactive'\n  | 'assistant-run-as-not-member'\n  | 'assistant-run-as-not-permitted'\n\nexport interface RunAsChecks<TUser, TDomain> {\n  /** The user as stored now - not as the caller last saw them. */\n  findUser: (id: string) => Promise<TUser | undefined | null>\n  /** Whether they can enter this domain - auth-base `canUserCheckinDomain`. */\n  mayCheckin: (user: TUser, domain: TDomain) => Promise<boolean>\n  /** auth-base `checkPermission`, with no address and no prohibitions: there is no request. */\n  permits: (gate: typeof ASK_ASSISTANT_GATE, user: TUser, domain: TDomain) => Promise<boolean>\n}\n\n/** `user` is the account as `findUser` read it just now - absent when there is none. */\nexport async function judgeRunAs<TUser extends { id?: string; status?: string }, TDomain>(\n  user: TUser | undefined | null,\n  domain: TDomain,\n  checks: Omit<RunAsChecks<TUser, TDomain>, 'findUser'>\n): Promise<{ user: TUser } | { refused: RunAsRefusal }> {\n  if (!user) return { refused: 'assistant-run-as-unknown' }\n  /* Only an account that can sign in now. Locked, banned, deleted, or one waiting for a password reset is not. */\n  if (user.status !== 'activated') return { refused: 'assistant-run-as-inactive' }\n  if (!(await checks.mayCheckin(user, domain))) return { refused: 'assistant-run-as-not-member' }\n  if (!(await checks.permits(ASK_ASSISTANT_GATE, user, domain))) return { refused: 'assistant-run-as-not-permitted' }\n  return { user }\n}\n"]}

package/dist-server/service/unattended-run/run-budget.d.ts

@@ -0,0 +1,24 @@
+import type { AgentClient } from '@things-factory/ai-client-base';
+export interface RunSpend {
+    modelCalls: number;
+    inputTokens: number;
+    outputTokens: number;
+    /** Set once a request was refused, with the limit it hit. */
+    exceeded?: {
+        limit: 'model-calls' | 'tokens';
+        max: number;
+        used: number;
+    };
+}
+export declare class RunBudgetExceeded extends Error {
+    readonly params: NonNullable<RunSpend['exceeded']>;
+    readonly code = "assistant-run-budget-exceeded";
+    constructor(params: NonNullable<RunSpend['exceeded']>);
+}
+export declare function budgetedClient(client: AgentClient, limits: {
+    maxModelCalls: number;
+    maxTokens: number;
+}): {
+    client: AgentClient;
+    spend: RunSpend;
+};

package/dist-server/service/unattended-run/run-budget.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunBudgetExceeded = void 0;
+exports.budgetedClient = budgetedClient;
+class RunBudgetExceeded extends Error {
+    constructor(params) {
+        super(`the run reached its ${params.limit} limit (${params.used} of ${params.max})`);
+        this.params = params;
+        this.code = 'assistant-run-budget-exceeded';
+    }
+}
+exports.RunBudgetExceeded = RunBudgetExceeded;
+function budgetedClient(client, limits) {
+    const spend = { modelCalls: 0, inputTokens: 0, outputTokens: 0 };
+    const admit = () => {
+        if (spend.modelCalls >= limits.maxModelCalls) {
+            spend.exceeded ??= { limit: 'model-calls', max: limits.maxModelCalls, used: spend.modelCalls };
+        }
+        else if (spend.inputTokens + spend.outputTokens >= limits.maxTokens) {
+            spend.exceeded ??= { limit: 'tokens', max: limits.maxTokens, used: spend.inputTokens + spend.outputTokens };
+        }
+        if (spend.exceeded)
+            throw new RunBudgetExceeded(spend.exceeded);
+        spend.modelCalls++;
+    };
+    const counted = (options) => ({
+        ...options,
+        onUsage: (usage) => {
+            spend.inputTokens += Number(usage?.inputTokens) || 0;
+            spend.outputTokens += Number(usage?.outputTokens) || 0;
+            options?.onUsage?.(usage);
+        }
+    });
+    const wrapped = {
+        id: client.id,
+        agent: client.agent,
+        chat: (messages, options) => (admit(), client.chat(messages, counted(options))),
+        generateJSON: (prompt, options) => (admit(), client.generateJSON(prompt, counted(options))),
+        ...(client.chatWithTools && {
+            chatWithTools: (messages, tools, options) => (admit(), client.chatWithTools(messages, tools, counted(options)))
+        }),
+        listModels: () => client.listModels()
+    };
+    return { client: wrapped, spend };
+}
+//# sourceMappingURL=run-budget.js.map

package/dist-server/service/unattended-run/run-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-budget.js","sourceRoot":"","sources":["../../../server/service/unattended-run/run-budget.ts"],"names":[],"mappings":";;;AAwBA,wCAiCC;AAxCD,MAAa,iBAAkB,SAAQ,KAAK;IAE1C,YAAqB,MAAyC;QAC5D,KAAK,CAAC,uBAAuB,MAAM,CAAC,KAAK,WAAW,MAAM,CAAC,IAAI,OAAO,MAAM,CAAC,GAAG,GAAG,CAAC,CAAA;QADjE,WAAM,GAAN,MAAM,CAAmC;QADrD,SAAI,GAAG,+BAA+B,CAAA;IAG/C,CAAC;CACF;AALD,8CAKC;AAED,SAAgB,cAAc,CAAC,MAAmB,EAAE,MAAoD;IACtG,MAAM,KAAK,GAAa,EAAE,UAAU,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAA;IAE1E,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,IAAI,KAAK,CAAC,UAAU,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;YAC7C,KAAK,CAAC,QAAQ,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,CAAC,aAAa,EAAE,IAAI,EAAE,KAAK,CAAC,UAAU,EAAE,CAAA;QAChG,CAAC;aAAM,IAAI,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,YAAY,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACtE,KAAK,CAAC,QAAQ,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,YAAY,EAAE,CAAA;QAC7G,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ;YAAE,MAAM,IAAI,iBAAiB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QAC/D,KAAK,CAAC,UAAU,EAAE,CAAA;IACpB,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,CAAC,OAAY,EAAE,EAAE,CAAC,CAAC;QACjC,GAAG,OAAO;QACV,OAAO,EAAE,CAAC,KAAU,EAAE,EAAE;YACtB,KAAK,CAAC,WAAW,IAAI,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,CAAC,CAAA;YACpD,KAAK,CAAC,YAAY,IAAI,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,CAAA;YACtD,OAAO,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,CAAA;QAC3B,CAAC;KACF,CAAC,CAAA;IAEF,MAAM,OAAO,GAAgB;QAC3B,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,IAAI,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QAC/E,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3F,GAAG,CAAC,MAAM,CAAC,aAAa,IAAI;YAC1B,aAAa,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,aAAc,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;SACjH,CAAC;QACF,UAAU,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE;KACvB,CAAA;IAChB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;AACnC,CAAC","sourcesContent":["/*\n * The client one unattended run talks through - it counts what the run spends and refuses the request past the limit\n * (design/ai/unattended-run.md §4).\n *\n * It wraps the domain's metered client, so every request still writes its AiUsage row at the provider boundary\n * (ADR-0061 decision 6); this only adds the run's own ceiling.\n */\nimport type { AgentClient } from '@things-factory/ai-client-base'\n\nexport interface RunSpend {\n  modelCalls: number\n  inputTokens: number\n  outputTokens: number\n  /** Set once a request was refused, with the limit it hit. */\n  exceeded?: { limit: 'model-calls' | 'tokens'; max: number; used: number }\n}\n\nexport class RunBudgetExceeded extends Error {\n  readonly code = 'assistant-run-budget-exceeded'\n  constructor(readonly params: NonNullable<RunSpend['exceeded']>) {\n    super(`the run reached its ${params.limit} limit (${params.used} of ${params.max})`)\n  }\n}\n\nexport function budgetedClient(client: AgentClient, limits: { maxModelCalls: number; maxTokens: number }): { client: AgentClient; spend: RunSpend } {\n  const spend: RunSpend = { modelCalls: 0, inputTokens: 0, outputTokens: 0 }\n\n  const admit = () => {\n    if (spend.modelCalls >= limits.maxModelCalls) {\n      spend.exceeded ??= { limit: 'model-calls', max: limits.maxModelCalls, used: spend.modelCalls }\n    } else if (spend.inputTokens + spend.outputTokens >= limits.maxTokens) {\n      spend.exceeded ??= { limit: 'tokens', max: limits.maxTokens, used: spend.inputTokens + spend.outputTokens }\n    }\n    if (spend.exceeded) throw new RunBudgetExceeded(spend.exceeded)\n    spend.modelCalls++\n  }\n\n  const counted = (options: any) => ({\n    ...options,\n    onUsage: (usage: any) => {\n      spend.inputTokens += Number(usage?.inputTokens) || 0\n      spend.outputTokens += Number(usage?.outputTokens) || 0\n      options?.onUsage?.(usage)\n    }\n  })\n\n  const wrapped: AgentClient = {\n    id: client.id,\n    agent: client.agent,\n    chat: (messages, options) => (admit(), client.chat(messages, counted(options))),\n    generateJSON: (prompt, options) => (admit(), client.generateJSON(prompt, counted(options))),\n    ...(client.chatWithTools && {\n      chatWithTools: (messages, tools, options) => (admit(), client.chatWithTools!(messages, tools, counted(options)))\n    }),\n    listModels: () => client.listModels()\n  } as AgentClient\n  return { client: wrapped, spend }\n}\n"]}

package/dist-server/service/unattended-run/run-ledger.d.ts

@@ -0,0 +1,13 @@
+export type AssistantRunStatus = 'running' | 'succeeded' | 'failed' | 'refused';
+export interface LedgerRow {
+    status: AssistantRunStatus | string;
+    deadlineAt?: Date | string | null;
+}
+/**
+ * `return` - hand the stored row back, run nothing. `retake` - start the next attempt on the same row.
+ *
+ * A succeeded run is the answer. A running one is left alone until its deadline; past it the server that held it is
+ * taken as gone. A failed or refused one runs again - a retry is for exactly that, and how many retries there are is
+ * the caller's limit (scheduler-client `max_retry_count`), not this one's.
+ */
+export declare function nextStep(row: LedgerRow, now: Date): 'return' | 'retake';

package/dist-server/service/unattended-run/run-ledger.js

@@ -0,0 +1,29 @@
+"use strict";
+/*
+ * Pure. What a call for an occurrence that already has a row does (design/ai/unattended-run.md §5).
+ *
+ * One row is one occurrence - (domain, source, subject, scheduledAt). scheduler-client calls again when an answer came
+ * late or failed; a second call must not run the model a second time while the first is alive or after it succeeded.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextStep = nextStep;
+/**
+ * `return` - hand the stored row back, run nothing. `retake` - start the next attempt on the same row.
+ *
+ * A succeeded run is the answer. A running one is left alone until its deadline; past it the server that held it is
+ * taken as gone. A failed or refused one runs again - a retry is for exactly that, and how many retries there are is
+ * the caller's limit (scheduler-client `max_retry_count`), not this one's.
+ */
+function nextStep(row, now) {
+    if (row.status === 'succeeded')
+        return 'return';
+    if (row.status === 'running') {
+        const deadline = row.deadlineAt ? new Date(row.deadlineAt).valueOf() : NaN;
+        /* A running row with no readable deadline is not taken over - two runs at once is the one thing this prevents. */
+        if (!Number.isFinite(deadline))
+            return 'return';
+        return deadline > now.valueOf() ? 'return' : 'retake';
+    }
+    return 'retake';
+}
+//# sourceMappingURL=run-ledger.js.map

package/dist-server/service/unattended-run/run-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-ledger.js","sourceRoot":"","sources":["../../../server/service/unattended-run/run-ledger.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAgBH,4BASC;AAhBD;;;;;;GAMG;AACH,SAAgB,QAAQ,CAAC,GAAc,EAAE,GAAS;IAChD,IAAI,GAAG,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,QAAQ,CAAA;IAC/C,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,GAAG,CAAA;QAC1E,kHAAkH;QAClH,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,OAAO,QAAQ,CAAA;QAC/C,OAAO,QAAQ,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAA;IACvD,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC","sourcesContent":["/*\n * Pure. What a call for an occurrence that already has a row does (design/ai/unattended-run.md §5).\n *\n * One row is one occurrence - (domain, source, subject, scheduledAt). scheduler-client calls again when an answer came\n * late or failed; a second call must not run the model a second time while the first is alive or after it succeeded.\n */\n\nexport type AssistantRunStatus = 'running' | 'succeeded' | 'failed' | 'refused'\n\nexport interface LedgerRow {\n  status: AssistantRunStatus | string\n  deadlineAt?: Date | string | null\n}\n\n/**\n * `return` - hand the stored row back, run nothing. `retake` - start the next attempt on the same row.\n *\n * A succeeded run is the answer. A running one is left alone until its deadline; past it the server that held it is\n * taken as gone. A failed or refused one runs again - a retry is for exactly that, and how many retries there are is\n * the caller's limit (scheduler-client `max_retry_count`), not this one's.\n */\nexport function nextStep(row: LedgerRow, now: Date): 'return' | 'retake' {\n  if (row.status === 'succeeded') return 'return'\n  if (row.status === 'running') {\n    const deadline = row.deadlineAt ? new Date(row.deadlineAt).valueOf() : NaN\n    /* A running row with no readable deadline is not taken over - two runs at once is the one thing this prevents. */\n    if (!Number.isFinite(deadline)) return 'return'\n    return deadline > now.valueOf() ? 'return' : 'retake'\n  }\n  return 'retake'\n}\n"]}

package/dist-server/service/unattended-run/run-outcome.d.ts

@@ -0,0 +1,9 @@
+export declare const outcomeKey: (code: string) => string;
+export declare const ASSISTANT_RUN_OUTCOME_ENGLISH: Record<string, string>;
+type Translate = (key: string, options?: Record<string, unknown>) => string;
+/** The sentence for a run's outcome, or undefined when it has none (running, or succeeded). */
+export declare function assistantRunOutcomeText(run: {
+    outcomeCode?: string | null;
+    outcomeParams?: string | null;
+}, t?: Translate): string | undefined;
+export {};

package/dist-server/service/unattended-run/run-outcome.js

@@ -0,0 +1,46 @@
+"use strict";
+/*
+ * Why a run failed or was refused, as a person reads it (design/ai/unattended-run.md §7).
+ *
+ * The run keeps a code and its values (ADR-0054); the sentence is made where it is shown, under this package's key
+ * `ai-assistant.run.<code>` - an outcome is a stored value, not a thrown refusal. The English below is the sentence
+ * when no translation has the key; the application that shows a run does not write its own.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASSISTANT_RUN_OUTCOME_ENGLISH = exports.outcomeKey = void 0;
+exports.assistantRunOutcomeText = assistantRunOutcomeText;
+const outcomeKey = (code) => `ai-assistant.run.${code}`;
+exports.outcomeKey = outcomeKey;
+exports.ASSISTANT_RUN_OUTCOME_ENGLISH = {
+    'assistant-run-as-unknown': 'the account the run was to act as does not exist.',
+    'assistant-run-as-inactive': "the owner's account is not active, so the run did not start.",
+    'assistant-run-as-not-member': 'the owner can no longer enter this domain, so the run did not start.',
+    'assistant-run-as-not-permitted': 'the owner may no longer ask the AI assistant, so the run did not start.',
+    'assistant-mode-not-unattended': 'the assistant mode {kind} does not run without a person.',
+    'unknown-assistant-mode': 'this server has no assistant mode {kind}.',
+    'assistant-run-budget-exceeded': 'the run reached its {limit} limit ({used} of {max}) and stopped.',
+    'assistant-run-step-limit': 'the run did not finish within {steps} steps.',
+    'assistant-run-timeout': 'the run did not finish within {timeoutMs} ms.',
+    'assistant-run-empty-draft': 'the run ended without writing a draft.',
+    'assistant-run-model-error': 'the AI model failed during the run.',
+    'assistant-run-abandoned': 'the run stopped partway and was started again.',
+    'ai-not-configured': 'AI is not set up for this domain.',
+    'ai-agent-not-available': 'the AI agent picked for this run is not available here.'
+};
+/** The sentence for a run's outcome, or undefined when it has none (running, or succeeded). */
+function assistantRunOutcomeText(run, t) {
+    const code = run?.outcomeCode;
+    if (!code)
+        return undefined;
+    let params = {};
+    try {
+        params = run.outcomeParams ? JSON.parse(run.outcomeParams) : {};
+    }
+    catch {
+        params = {};
+    }
+    const english = exports.ASSISTANT_RUN_OUTCOME_ENGLISH[code] ?? code;
+    const fill = (text) => text.replace(/\{(\w+)\}/g, (_, name) => (params[name] === undefined ? `{${name}}` : String(params[name])));
+    return t ? t((0, exports.outcomeKey)(code), { ...params, defaultValue: english }) : fill(english);
+}
+//# sourceMappingURL=run-outcome.js.map

package/dist-server/service/unattended-run/run-outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-outcome.js","sourceRoot":"","sources":["../../../server/service/unattended-run/run-outcome.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAwBH,0DAYC;AAlCM,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,oBAAoB,IAAI,EAAE,CAAA;AAAzD,QAAA,UAAU,cAA+C;AAEzD,QAAA,6BAA6B,GAA2B;IACnE,0BAA0B,EAAE,mDAAmD;IAC/E,2BAA2B,EAAE,8DAA8D;IAC3F,6BAA6B,EAAE,sEAAsE;IACrG,gCAAgC,EAAE,yEAAyE;IAC3G,+BAA+B,EAAE,0DAA0D;IAC3F,wBAAwB,EAAE,2CAA2C;IACrE,+BAA+B,EAAE,kEAAkE;IACnG,0BAA0B,EAAE,8CAA8C;IAC1E,uBAAuB,EAAE,+CAA+C;IACxE,2BAA2B,EAAE,wCAAwC;IACrE,2BAA2B,EAAE,qCAAqC;IAClE,yBAAyB,EAAE,gDAAgD;IAC3E,mBAAmB,EAAE,mCAAmC;IACxD,wBAAwB,EAAE,yDAAyD;CACpF,CAAA;AAID,+FAA+F;AAC/F,SAAgB,uBAAuB,CAAC,GAAmE,EAAE,CAAa;IACxH,MAAM,IAAI,GAAG,GAAG,EAAE,WAAW,CAAA;IAC7B,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAA;IAC3B,IAAI,MAAM,GAA4B,EAAE,CAAA;IACxC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,EAAE,CAAA;IACb,CAAC;IACD,MAAM,OAAO,GAAG,qCAA6B,CAAC,IAAI,CAAC,IAAI,IAAI,CAAA;IAC3D,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;IACzI,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAA,kBAAU,EAAC,IAAI,CAAC,EAAE,EAAE,GAAG,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AACtF,CAAC","sourcesContent":["/*\n * Why a run failed or was refused, as a person reads it (design/ai/unattended-run.md §7).\n *\n * The run keeps a code and its values (ADR-0054); the sentence is made where it is shown, under this package's key\n * `ai-assistant.run.<code>` - an outcome is a stored value, not a thrown refusal. The English below is the sentence\n * when no translation has the key; the application that shows a run does not write its own.\n */\n\nexport const outcomeKey = (code: string) => `ai-assistant.run.${code}`\n\nexport const ASSISTANT_RUN_OUTCOME_ENGLISH: Record<string, string> = {\n  'assistant-run-as-unknown': 'the account the run was to act as does not exist.',\n  'assistant-run-as-inactive': \"the owner's account is not active, so the run did not start.\",\n  'assistant-run-as-not-member': 'the owner can no longer enter this domain, so the run did not start.',\n  'assistant-run-as-not-permitted': 'the owner may no longer ask the AI assistant, so the run did not start.',\n  'assistant-mode-not-unattended': 'the assistant mode {kind} does not run without a person.',\n  'unknown-assistant-mode': 'this server has no assistant mode {kind}.',\n  'assistant-run-budget-exceeded': 'the run reached its {limit} limit ({used} of {max}) and stopped.',\n  'assistant-run-step-limit': 'the run did not finish within {steps} steps.',\n  'assistant-run-timeout': 'the run did not finish within {timeoutMs} ms.',\n  'assistant-run-empty-draft': 'the run ended without writing a draft.',\n  'assistant-run-model-error': 'the AI model failed during the run.',\n  'assistant-run-abandoned': 'the run stopped partway and was started again.',\n  'ai-not-configured': 'AI is not set up for this domain.',\n  'ai-agent-not-available': 'the AI agent picked for this run is not available here.'\n}\n\ntype Translate = (key: string, options?: Record<string, unknown>) => string\n\n/** The sentence for a run's outcome, or undefined when it has none (running, or succeeded). */\nexport function assistantRunOutcomeText(run: { outcomeCode?: string | null; outcomeParams?: string | null }, t?: Translate): string | undefined {\n  const code = run?.outcomeCode\n  if (!code) return undefined\n  let params: Record<string, unknown> = {}\n  try {\n    params = run.outcomeParams ? JSON.parse(run.outcomeParams) : {}\n  } catch {\n    params = {}\n  }\n  const english = ASSISTANT_RUN_OUTCOME_ENGLISH[code] ?? code\n  const fill = (text: string) => text.replace(/\\{(\\w+)\\}/g, (_, name) => (params[name] === undefined ? `{${name}}` : String(params[name])))\n  return t ? t(outcomeKey(code), { ...params, defaultValue: english }) : fill(english)\n}\n"]}

package/dist-server/service/unattended-run/run-store.d.ts

@@ -0,0 +1,31 @@
+import type { Repository } from 'typeorm';
+import { AssistantRun } from './assistant-run.js';
+export interface RunIdentity {
+    domainId: string;
+    source: string;
+    subject: string;
+    scheduledAt: Date;
+}
+export interface RunStart {
+    name: string;
+    modeKind: string;
+    modeTarget?: string;
+    /** Absent when the account named does not exist - the row still says the run was refused. */
+    runAsId?: string;
+    startedAt: Date;
+    deadlineAt: Date;
+}
+export type RunEnding = Partial<Pick<AssistantRun, 'status' | 'finishedAt' | 'draft' | 'reads' | 'doors' | 'outcomeCode' | 'outcomeParams' | 'groundingWarnings' | 'agentId' | 'clientId' | 'modelCalls' | 'inputTokens' | 'outputTokens' | 'cardsDropped'>>;
+export interface RunStore {
+    /** The row of this occurrence, and whether this call holds its attempt now. */
+    claim(identity: RunIdentity, start: RunStart, now: Date): Promise<{
+        claimed: boolean;
+        row: AssistantRun;
+    }>;
+    /** Ends the attempt the caller holds. A later attempt's row is returned untouched. */
+    finish(held: {
+        id: string;
+        attempt: number;
+    }, ending: RunEnding): Promise<AssistantRun>;
+}
+export declare function typeormRunStore(repository: () => Repository<AssistantRun>): RunStore;

package/dist-server/service/unattended-run/run-store.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.typeormRunStore = typeormRunStore;
+const assistant_run_js_1 = require("./assistant-run.js");
+const run_ledger_js_1 = require("./run-ledger.js");
+/** What a fresh attempt starts with - nothing of the attempt before it. */
+const CLEARED = {
+    finishedAt: null,
+    draft: null,
+    reads: null,
+    doors: null,
+    outcomeCode: null,
+    outcomeParams: null,
+    groundingWarnings: null,
+    agentId: null,
+    clientId: null,
+    modelCalls: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    cardsDropped: 0
+};
+function endingOf(row) {
+    /* A running attempt being taken over did not end by itself - it is closed as abandoned. */
+    const abandoned = row.status === 'running';
+    return {
+        attempt: row.attempt,
+        status: abandoned ? 'failed' : row.status,
+        outcomeCode: abandoned ? 'assistant-run-abandoned' : row.outcomeCode ?? null,
+        startedAt: row.startedAt ?? null,
+        finishedAt: abandoned ? null : row.finishedAt ?? null
+    };
+}
+function typeormRunStore(repository) {
+    const where = (identity) => ({
+        domain: { id: identity.domainId },
+        source: identity.source,
+        subject: identity.subject,
+        scheduledAt: identity.scheduledAt
+    });
+    const read = (identity) => repository().findOne({ where: where(identity) });
+    async function retake(row, start) {
+        const history = [...(row.attemptsJson ?? []), endingOf(row)];
+        const result = await repository()
+            .createQueryBuilder()
+            .update(assistant_run_js_1.AssistantRun)
+            .set({
+            ...CLEARED,
+            status: 'running',
+            attempt: row.attempt + 1,
+            attempts: JSON.stringify(history),
+            startedAt: start.startedAt,
+            deadlineAt: start.deadlineAt,
+            modeKind: start.modeKind,
+            modeTarget: start.modeTarget ?? null,
+            runAs: start.runAsId ? { id: start.runAsId } : null,
+            updater: start.runAsId ? { id: start.runAsId } : null
+        })
+            .where('id = :id AND attempt = :attempt AND status = :status', { id: row.id, attempt: row.attempt, status: row.status })
+            .execute();
+        return result.affected === 1;
+    }
+    return {
+        async claim(identity, start, now) {
+            let row = await read(identity);
+            if (!row) {
+                try {
+                    await repository().insert({
+                        ...where(identity),
+                        name: start.name,
+                        modeKind: start.modeKind,
+                        modeTarget: start.modeTarget,
+                        ...(start.runAsId ? { runAs: { id: start.runAsId }, creator: { id: start.runAsId }, updater: { id: start.runAsId } } : {}),
+                        status: 'running',
+                        attempt: 1,
+                        startedAt: start.startedAt,
+                        deadlineAt: start.deadlineAt,
+                        modelCalls: 0,
+                        inputTokens: 0,
+                        outputTokens: 0,
+                        cardsDropped: 0
+                    });
+                    return { claimed: true, row: (await read(identity)) };
+                }
+                catch (error) {
+                    /* Another call made the row first - the unique index said so. Anything else is not that and is thrown. */
+                    row = await read(identity);
+                    if (!row)
+                        throw error;
+                    return { claimed: false, row };
+                }
+            }
+            if ((0, run_ledger_js_1.nextStep)(row, now) === 'return')
+                return { claimed: false, row };
+            const took = await retake(row, start);
+            return { claimed: took, row: (await read(identity)) };
+        },
+        async finish(held, ending) {
+            await repository()
+                .createQueryBuilder()
+                .update(assistant_run_js_1.AssistantRun)
+                .set(ending)
+                .where('id = :id AND attempt = :attempt AND status = :status', { id: held.id, attempt: held.attempt, status: 'running' })
+                .execute();
+            return (await repository().findOne({ where: { id: held.id } }));
+        }
+    };
+}
+//# sourceMappingURL=run-store.js.map

package/dist-server/service/unattended-run/run-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-store.js","sourceRoot":"","sources":["../../../server/service/unattended-run/run-store.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Where runs are kept - one row per occurrence, attempts on the same row (design/ai/unattended-run.md §5).\n *\n * Two calls for one occurrence at once are parted by the unique index: one insert wins, the other reads the row it\n * made. Taking an occurrence over is one update guarded by the attempt it saw, so two servers cannot both take it.\n * Finishing is guarded the same way: an attempt that was taken over and ends late does not write over the next one.\n */\nimport type { Repository } from 'typeorm'\n\nimport { AssistantRun } from './assistant-run.js'\nimport { nextStep } from './run-ledger.js'\n\nexport interface RunIdentity {\n  domainId: string\n  source: string\n  subject: string\n  scheduledAt: Date\n}\n\nexport interface RunStart {\n  name: string\n  modeKind: string\n  modeTarget?: string\n  /** Absent when the account named does not exist - the row still says the run was refused. */\n  runAsId?: string\n  startedAt: Date\n  deadlineAt: Date\n}\n\nexport type RunEnding = Partial<\n  Pick<\n    AssistantRun,\n    | 'status'\n    | 'finishedAt'\n    | 'draft'\n    | 'reads'\n    | 'doors'\n    | 'outcomeCode'\n    | 'outcomeParams'\n    | 'groundingWarnings'\n    | 'agentId'\n    | 'clientId'\n    | 'modelCalls'\n    | 'inputTokens'\n    | 'outputTokens'\n    | 'cardsDropped'\n  >\n>\n\nexport interface RunStore {\n  /** The row of this occurrence, and whether this call holds its attempt now. */\n  claim(identity: RunIdentity, start: RunStart, now: Date): Promise<{ claimed: boolean; row: AssistantRun }>\n  /** Ends the attempt the caller holds. A later attempt's row is returned untouched. */\n  finish(held: { id: string; attempt: number }, ending: RunEnding): Promise<AssistantRun>\n}\n\n/** What a fresh attempt starts with - nothing of the attempt before it. */\nconst CLEARED = {\n  finishedAt: null,\n  draft: null,\n  reads: null,\n  doors: null,\n  outcomeCode: null,\n  outcomeParams: null,\n  groundingWarnings: null,\n  agentId: null,\n  clientId: null,\n  modelCalls: 0,\n  inputTokens: 0,\n  outputTokens: 0,\n  cardsDropped: 0\n}\n\nfunction endingOf(row: AssistantRun) {\n  /* A running attempt being taken over did not end by itself - it is closed as abandoned. */\n  const abandoned = row.status === 'running'\n  return {\n    attempt: row.attempt,\n    status: abandoned ? 'failed' : row.status,\n    outcomeCode: abandoned ? 'assistant-run-abandoned' : row.outcomeCode ?? null,\n    startedAt: row.startedAt ?? null,\n    finishedAt: abandoned ? null : row.finishedAt ?? null\n  }\n}\n\nexport function typeormRunStore(repository: () => Repository<AssistantRun>): RunStore {\n  const where = (identity: RunIdentity) => ({\n    domain: { id: identity.domainId },\n    source: identity.source,\n    subject: identity.subject,\n    scheduledAt: identity.scheduledAt\n  })\n\n  const read = (identity: RunIdentity) => repository().findOne({ where: where(identity) as any })\n\n  async function retake(row: AssistantRun, start: RunStart): Promise<boolean> {\n    const history = [...((row as any).attemptsJson ?? []), endingOf(row)]\n    const result = await repository()\n      .createQueryBuilder()\n      .update(AssistantRun)\n      .set({\n        ...CLEARED,\n        status: 'running',\n        attempt: row.attempt + 1,\n        attempts: JSON.stringify(history),\n        startedAt: start.startedAt,\n        deadlineAt: start.deadlineAt,\n        modeKind: start.modeKind,\n        modeTarget: start.modeTarget ?? null,\n        runAs: start.runAsId ? { id: start.runAsId } : null,\n        updater: start.runAsId ? { id: start.runAsId } : null\n      } as any)\n      .where('id = :id AND attempt = :attempt AND status = :status', { id: row.id, attempt: row.attempt, status: row.status })\n      .execute()\n    return result.affected === 1\n  }\n\n  return {\n    async claim(identity, start, now) {\n      let row = await read(identity)\n      if (!row) {\n        try {\n          await repository().insert({\n            ...where(identity),\n            name: start.name,\n            modeKind: start.modeKind,\n            modeTarget: start.modeTarget,\n            ...(start.runAsId ? { runAs: { id: start.runAsId }, creator: { id: start.runAsId }, updater: { id: start.runAsId } } : {}),\n            status: 'running',\n            attempt: 1,\n            startedAt: start.startedAt,\n            deadlineAt: start.deadlineAt,\n            modelCalls: 0,\n            inputTokens: 0,\n            outputTokens: 0,\n            cardsDropped: 0\n          } as any)\n          return { claimed: true, row: (await read(identity))! }\n        } catch (error) {\n          /* Another call made the row first - the unique index said so. Anything else is not that and is thrown. */\n          row = await read(identity)\n          if (!row) throw error\n          return { claimed: false, row }\n        }\n      }\n\n      if (nextStep(row, now) === 'return') return { claimed: false, row }\n      const took = await retake(row, start)\n      return { claimed: took, row: (await read(identity))! }\n    },\n\n    async finish(held, ending) {\n      await repository()\n        .createQueryBuilder()\n        .update(AssistantRun)\n        .set(ending as any)\n        .where('id = :id AND attempt = :attempt AND status = :status', { id: held.id, attempt: held.attempt, status: 'running' })\n        .execute()\n      return (await repository().findOne({ where: { id: held.id } as any }))!\n    }\n  }\n}\n"]}

package/dist-server/service/unattended-run/run-unattended.d.ts

@@ -0,0 +1,50 @@
+import { type AgentClient, type AiClientRequest, type ToolAccessCheck } from '@things-factory/ai-client-base';
+import { AssistantRun } from './assistant-run.js';
+import { type RunAsChecks } from './run-as.js';
+import { type RunStore } from './run-store.js';
+export interface UnattendedRunInput {
+    /** The domain the run is in, as loaded - its parent and owner decide who can enter it. */
+    domain: {
+        id: string;
+        [key: string]: any;
+    };
+    /** The user the run acts as - the policy owner. Their privileges and doors only. */
+    runAs: string;
+    /** Which occurrence this is. The same three again is the same run. */
+    run: {
+        /** Who scheduled it - `<app>.<work>`, e.g. `office.strategy-review`. */
+        source: string;
+        /** What it is about in the source's terms - a policy id. */
+        subject: string;
+        scheduledAt: Date;
+    };
+    /** A registered mode that declares `unattended`. */
+    mode: {
+        kind: string;
+        target?: string;
+    };
+    /** What this occurrence is asked to do - the caller server's text, read by the model (English). */
+    instruction: string;
+    /** What the run is about, for the tools. Filled by the caller's server; still never used for authorization. */
+    hostContext?: Record<string, any>;
+    /** The language of the draft - the owner's. Absent: their account's locale. */
+    lng?: string;
+}
+/** What the run reaches outside itself. The defaults are the server's; the tests hand their own. */
+export interface UnattendedRunDeps {
+    store: RunStore;
+    runAs: RunAsChecks<any, any>;
+    clientFor: (request: AiClientRequest) => Promise<AgentClient>;
+    toolAccess: (state: any) => ToolAccessCheck;
+    now: () => Date;
+}
+export declare function runAssistantUnattended(input: UnattendedRunInput, deps?: UnattendedRunDeps): Promise<AssistantRun>;
+/** The stored run of an occurrence, for the application that scheduled it - read behind that application's own door. */
+export declare function findAssistantRun(identity: {
+    domainId: string;
+    source: string;
+    subject: string;
+    scheduledAt: Date;
+} | {
+    id: string;
+}): Promise<AssistantRun | null>;