bazis 0.129.0 → 0.131.0

package/core/agent/AgentToolExecutor.ts

@@ -58,6 +58,8 @@ export interface AgentToolExecutionContext {
   readonly maxAttempts: number;
   readonly idempotencyKey?: string;
   readonly approval: AgentToolExecutionApproval;
+  /** On whose behalf the call runs, when the caller says so. */
+  readonly actor?: ToolActor;
   readonly metadata: JsonObject;
   readonly signal: AbortSignal;
 }
@@ -1664,6 +1666,7 @@ export class AgentToolExecutor {
       maxAttempts: attempt.maxAttempts,
       ...(attempt.idempotencyKey !== undefined ? { idempotencyKey: attempt.idempotencyKey } : {}),
       approval,
+      ...(options.actor !== undefined ? { actor: options.actor } : {}),
       metadata,
       signal,
     });

package/core/agent/Tool.contract.ts

@@ -15,6 +15,6 @@ export function describeTool(tool: ToolDefinition) {
     name: tool.metadata.name, description: tool.metadata.description,
     input: tool.metadata.input ? schema(tool.metadata.input) : undefined,
     output: tool.metadata.output ? schema(tool.metadata.output) : undefined,
-    sideEffect: tool.metadata.sideEffect, approval: tool.metadata.approval, timeoutMs: tool.metadata.timeoutMs,
+    sideEffect: tool.metadata.sideEffect, approval: tool.metadata.approval, timeoutMs: tool.metadata.timeoutMs, dryRun: tool.metadata.dryRun,
   });
 }

package/core/agent/index.ts

@@ -88,6 +88,7 @@ export {
   type ToolApproval,
   type ToolMetadata,
   type ToolActor,
+  type ToolDryRun,
   type ToolOptions,
   type ToolSideEffect,
 } from "./metadata";

package/core/agent/metadata.ts

@@ -15,6 +15,8 @@ export interface ToolActor {
   readonly id: string;
 }
 export type ToolApproval = "never" | "policy" | "required";
+/** Whether a Tool can run without changing anything, when a process is tried out (WORKFLOW-002 §5.4). */
+export type ToolDryRun = "supported" | "unsupported";
 
 export interface ToolOptions {
   readonly name: string;
@@ -24,6 +26,8 @@ export interface ToolOptions {
   readonly sideEffect?: ToolSideEffect;
   readonly approval?: ToolApproval;
   readonly timeoutMs?: number;
+  /** `"unsupported"` by default. */
+  readonly dryRun?: ToolDryRun;
   /**
    * Who may call the Tool: `"agent"` for LLM agents, any other id for code that
    * runs Tools itself (`ToolRunner.as("workflow")`). Required and non-empty;
@@ -42,6 +46,7 @@ export interface ToolMetadata {
   readonly sideEffect: ToolSideEffect;
   readonly approval: ToolApproval;
   readonly timeoutMs?: number;
+  readonly dryRun: ToolDryRun;
   readonly callers: readonly string[];
   readonly tags: readonly string[];
 }
@@ -103,6 +108,9 @@ export function defineToolMetadata(_target: object, metadata: object, options: T
   if (options.approval !== undefined && options.approval !== "never" && options.approval !== "policy" && options.approval !== "required") {
     throw new AgentSetupError("@Tool.approval must be never, policy or required.");
   }
+  if (options.dryRun !== undefined && options.dryRun !== "supported" && options.dryRun !== "unsupported") {
+    throw new AgentSetupError("@Tool.dryRun must be supported or unsupported.");
+  }
   const normalized: ToolMetadata = Object.freeze({
     name: text(options.name, "@Tool.name"),
     description: text(options.description, "@Tool.description"),
@@ -111,6 +119,7 @@ export function defineToolMetadata(_target: object, metadata: object, options: T
     sideEffect,
     approval: approvalFor(sideEffect, options.approval),
     timeoutMs: positiveInteger(options.timeoutMs, "@Tool.timeoutMs"),
+    dryRun: options.dryRun ?? "unsupported",
     // Checked when the module registers the Tool, so a missing list prints as
     // one configuration-error line at start instead of failing the import.
     callers: Array.isArray(options.callers) ? Object.freeze(options.callers.map((caller) => callerId(caller))) : Object.freeze([]),

package/core/agent/semantic.ts

@@ -1,5 +1,5 @@
 import { AgentSemanticError } from "./errors";
-import type { ToolApproval, ToolSideEffect } from "./metadata";
+import type { ToolApproval, ToolDryRun, ToolSideEffect } from "./metadata";
 
 const FORBIDDEN_JSON_KEYS = new Set(["__proto__", "prototype", "constructor"]);
 
@@ -162,6 +162,7 @@ export interface AgentToolContract {
   readonly sideEffect: ToolSideEffect;
   readonly approval: ToolApproval;
   readonly timeoutMs?: number;
+  readonly dryRun: ToolDryRun;
 }
 
 export interface AgentToolContractOptions {
@@ -172,6 +173,7 @@ export interface AgentToolContractOptions {
   readonly sideEffect?: ToolSideEffect;
   readonly approval?: ToolApproval;
   readonly timeoutMs?: number;
+  readonly dryRun?: ToolDryRun;
 }
 
 export interface AgentModelCapabilities {
@@ -533,6 +535,10 @@ export function agentToolContract(options: AgentToolContractOptions): AgentToolC
   if ((sideEffect === "write" || sideEffect === "external") && approval === "never") {
     throw new AgentSemanticError('write/external tools cannot use approval: "never".');
   }
+  const dryRun = options.dryRun ?? "unsupported";
+  if (dryRun !== "supported" && dryRun !== "unsupported") {
+    throw new AgentSemanticError("tool.dryRun must be supported or unsupported.");
+  }
   return freezeWithoutUndefined({
     name: requiredName(options.name, "tool.name"),
     description: requiredContentText(options.description, "tool.description"),
@@ -541,6 +547,7 @@ export function agentToolContract(options: AgentToolContractOptions): AgentToolC
     sideEffect,
     approval,
     timeoutMs: optionalPositiveInteger(options.timeoutMs, "tool.timeoutMs"),
+    dryRun,
   });
 }
 

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.129.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.131.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/workflow/contracts/types.ts

@@ -1,19 +1,42 @@
+import type { ListQuery, SortField } from "../../../library/jsonapi";
+
 /** Who acts: a user or the system (schedules, events). Steps of an instance run on behalf of who started it. */
 export interface WorkflowActor {
   readonly kind: "user" | "system";
   readonly id: string;
 }
 
+/** Where an action came from, for the audit: `null` in its place means code called. */
+export interface WorkflowRequest {
+  readonly ip: string | null;
+  readonly userAgent: string | null;
+}
+
+/** What the audit events of an action carry besides its actor. */
+export interface WorkflowAuditOptions {
+  readonly request?: WorkflowRequest | null;
+}
+
+/** What `context.metadata` holds when a process calls a Tool: enough to name the cause in its own events. */
+export interface WorkflowToolMetadata {
+  readonly instanceId: string;
+  readonly processKey: string;
+  readonly nodeId: string;
+  readonly partition: string | null;
+  readonly test: boolean;
+}
+
 /** A page of a list. */
 export interface WorkflowPage<T> {
   readonly items: readonly T[];
   readonly total: number;
 }
 
-/** Paging of the list operations: `limit` 1–200 (50 by default), `offset` from 0. */
+/** Paging of the list operations: `limit` 1–200 (50 by default), `offset` from 0; `sort` replaces the list's own order. */
 export interface WorkflowPaging {
   readonly limit?: number;
   readonly offset?: number;
+  readonly sort?: readonly SortField[];
 }
 
 export function pagingOf(paging: WorkflowPaging): { readonly limit: number; readonly offset: number } {
@@ -22,6 +45,19 @@ export function pagingOf(paging: WorkflowPaging): { readonly limit: number; read
   return { limit: Number.isFinite(limit) ? Math.min(Math.max(limit, 1), 200) : 50, offset: Number.isFinite(offset) ? Math.max(offset, 0) : 0 };
 }
 
+/** The page of a list operation as `paginate` takes it. */
+export function pageQueryOf(paging: WorkflowPaging, order: SortField): ListQuery {
+  const { limit, offset } = pagingOf(paging);
+  return {
+    sort: paging.sort ?? [order],
+    filters: [],
+    or: [],
+    include: [],
+    fields: {},
+    page: { limit, offset, size: limit, number: Math.floor(offset / limit) + 1 },
+  };
+}
+
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 /** Whether an id can be a row key; anything else would reach PostgreSQL as an invalid uuid. */

package/core/workflow/definitions_module/WorkflowDefinitions.module.ts

@@ -1,6 +1,10 @@
+import { AccessModule } from "../../access";
 import { HOSTED_SERVICE, Module, scoped, singleton } from "../../di";
 import { SystemWorkflowClock, WorkflowClock } from "../contracts/WorkflowClock";
+import { WorkflowEvents } from "../internal/WorkflowEvents";
 import { WorkflowTools } from "../internal/WorkflowTools";
+import { definitionsPermissions } from "./access/Definitions.permissions";
+import { ProcessReferences } from "./access/Process.references";
 import { CodeProcessCatalog } from "./code/CodeProcessCatalog";
 import { CodeProcessPublisher } from "./code/CodeProcessPublisher";
 import { ProcessesController } from "./http/Processes.controller";
@@ -15,15 +19,20 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
  * declared in code ([passport](MODULE.md)).
  */
 @Module({
+  imports: [AccessModule],
+  permissions: definitionsPermissions,
+  references: { "workflow.process": ProcessReferences },
   ormBazis: { context: DefinitionsDbContext, entities: [WfProcess, WfVersion], ownedStore: definitionsStore, registerRepositories: false },
   providers: [
     singleton(WorkflowClock, SystemWorkflowClock),
     singleton(WorkflowTools),
     singleton(CodeProcessCatalog),
+    scoped(WorkflowEvents),
     scoped(IWorkflowDefinitions, WorkflowDefinitions),
+    scoped(ProcessReferences),
     singleton(HOSTED_SERVICE, CodeProcessPublisher),
   ],
   controllers: [ProcessesController],
-  exports: [IWorkflowDefinitions, WorkflowTools, WorkflowClock],
+  exports: [IWorkflowDefinitions, WorkflowTools, WorkflowClock, WorkflowEvents],
 })
 export class WorkflowDefinitionsModule {}

package/core/workflow/definitions_module/access/Definitions.permissions.ts

@@ -0,0 +1,23 @@
+import { definePermissions } from "../../../access";
+
+const process = { ref: "workflow.process", column: "key" };
+
+/**
+ * The rights of the process catalog (WORKFLOW-002 §6.2). A process is one per
+ * application, so these have no partition until `WorkflowPartitions` connects
+ * processes to partitions (stage 4).
+ */
+export const definitionsPermissions = definePermissions({
+  "workflow.processes.read": {
+    title: { en: "See processes", ru: "Видеть процессы" },
+    on: { process },
+  },
+  "workflow.processes.manage": {
+    title: { en: "Edit processes", ru: "Редактировать процессы" },
+    on: { process },
+  },
+  "workflow.processes.publish": {
+    title: { en: "Publish processes", ru: "Публиковать процессы" },
+    on: { process },
+  },
+});

package/core/workflow/definitions_module/access/Process.references.ts

@@ -0,0 +1,27 @@
+import { References, type ReferenceItem, type ReferencePage } from "../../../access";
+import type { DefinitionsDbContext } from "../model/Definitions.dbContext";
+
+/** Reference kind `workflow.process`: what an administrator picks in a condition. */
+export class ProcessReferences extends References {
+  constructor(private readonly db: DefinitionsDbContext) {
+    super();
+  }
+
+  async exists(ids: readonly string[]): Promise<ReadonlySet<string>> {
+    return new Set((await this.describe(ids)).map((item) => item.id));
+  }
+
+  async describe(ids: readonly string[]): Promise<readonly ReferenceItem[]> {
+    if (ids.length === 0) return [];
+    const rows = await this.db.processes.asNoTracking().where((p) => p.key.in([...ids])).toList();
+    return rows.map((row) => ({ id: row.key, title: row.title }));
+  }
+
+  async search(text: string, _context: unknown, page: ReferencePage): Promise<readonly ReferenceItem[]> {
+    const found = text.trim();
+    let source = this.db.processes.asNoTracking();
+    if (found !== "") source = source.where((p) => p.key.contains(found, { ignoreCase: true }).or(p.title.contains(found, { ignoreCase: true })));
+    const rows = await source.orderBy((p) => p.key).skip(page.offset).take(page.limit).toList();
+    return rows.map((row) => ({ id: row.key, title: row.title }));
+  }
+}

package/core/workflow/definitions_module/events/Definitions.events.ts

@@ -0,0 +1,16 @@
+import { createEventToken } from "../../../kernel";
+import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
+
+export type ProcessChange = "created" | "updated" | "draftSaved" | "published" | "archived" | "restored";
+
+/** A process of the catalog changed, for the application's audit. Published after the commit. */
+export interface WorkflowProcessChanged {
+  readonly change: ProcessChange;
+  readonly key: string;
+  /** The version a `published` change made; otherwise `null`. */
+  readonly version: number | null;
+  readonly actor: WorkflowActor;
+  readonly request: WorkflowRequest | null;
+}
+
+export const WORKFLOW_PROCESS_CHANGED = createEventToken<WorkflowProcessChanged>("workflow.process-changed");

package/core/workflow/definitions_module/http/Processes.controller.ts

@@ -1,93 +1,107 @@
 import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
-import { Controller, Created, Get, Patch, Post, Put, type HttpContext } from "../../../http";
-import { authorize, body, optionalInteger, optionalString, pagingQuery, param, requiredString } from "../../internal/http";
+import { can } from "../../../access";
+import { Authorize, Controller, Created, Get, Patch, Post, Put, type HttpContext } from "../../../http";
+import { buildListDocument } from "../../../../library/jsonapi";
+import { body, callerOf, filterOf, listQuery, optionalInteger, optionalString, pagingOfList, param, requiredString } from "../../internal/http";
 import { WorkflowError } from "../../contracts/WorkflowError";
 import { IWorkflowDefinitions } from "../services/IWorkflowDefinitions.service";
 
-/** The process catalog over HTTP (WORKFLOW-001 §3); rights come from `WorkflowAccess`. */
+/** The process catalog over HTTP (WORKFLOW-001 §3); rights are `workflow.processes.*` (WORKFLOW-002 §6.2). */
 @Controller("workflow")
 export class ProcessesController {
   constructor(private readonly definitions: IWorkflowDefinitions) {}
 
   @Get("processes")
+  @Authorize(can("workflow.processes.read"))
   async list(ctx: HttpContext) {
-    await authorize(ctx, "processes.read");
-    const archived = ctx.query("archived");
+    const { access } = await callerOf(ctx);
+    const list = listQuery(ctx, { filter: { archived: ["eq"], search: ["eq"] }, sort: ["key", "title", "createdAt", "updatedAt"] });
+    const archived = filterOf(list, "archived");
     if (archived !== undefined && archived !== "true" && archived !== "false") throw new WorkflowError("invalid_input", "archived must be true or false");
-    const page = await this.definitions.list({ ...pagingQuery(ctx), archived: archived === undefined ? undefined : archived === "true", search: optionalString(ctx.query("search"), "search") });
-    return { data: page.items, meta: { total: page.total } };
+    const page = await this.definitions.list({ ...pagingOfList(list), access: await access.filter("workflow.processes.read"), archived: archived === undefined ? undefined : archived === "true", search: filterOf(list, "search") });
+    return buildListDocument(page.items, list, page.total, { basePath: ctx.path });
   }
 
   @Post("processes")
+  @Authorize(can("workflow.processes.manage"))
   async create(ctx: HttpContext) {
     const request = await body(ctx);
     const key = requiredString(request.key, "key", 64);
-    const actor = await authorize(ctx, "processes.manage", { processKey: key });
+    const { actor, request: from } = await callerOf(ctx, "workflow.processes.manage", { process: key });
     const process = await this.definitions.create({
       key,
       title: requiredString(request.title, "title"),
       description: optionalString(request.description, "description", 2000) ?? null,
       retentionDays: optionalInteger(request.retentionDays, "retentionDays") ?? null,
-    }, actor);
+    }, actor, { request: from });
     return Created(`${ctx.path}/${process.key}`, process);
   }
 
   @Get("processes/:key")
+  @Authorize(can("workflow.processes.read"))
   async get(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await authorize(ctx, "processes.read", { processKey: key });
+    await callerOf(ctx, "workflow.processes.read", { process: key });
     return await this.definitions.get(key);
   }
 
   @Patch("processes/:key")
+  @Authorize(can("workflow.processes.manage"))
   async update(ctx: HttpContext) {
     const key = param(ctx, "key");
     const request = await body(ctx);
-    const actor = await authorize(ctx, "processes.manage", { processKey: key });
+    const { actor, request: from } = await callerOf(ctx, "workflow.processes.manage", { process: key });
     if (request.archived !== undefined && typeof request.archived !== "boolean") throw new WorkflowError("invalid_input", "archived must be a boolean");
     return await this.definitions.update(key, {
       ...(request.title === undefined ? {} : { title: requiredString(request.title, "title") }),
       ...(request.description === undefined ? {} : { description: optionalString(request.description, "description", 2000) ?? null }),
       ...(request.retentionDays === undefined ? {} : { retentionDays: optionalInteger(request.retentionDays, "retentionDays") ?? null }),
       ...(request.archived === undefined ? {} : { archived: request.archived as boolean }),
-    }, actor);
+    }, actor, { request: from });
   }
 
   @Put("processes/:key/draft")
+  @Authorize(can("workflow.processes.manage"))
   async saveDraft(ctx: HttpContext) {
     const key = param(ctx, "key");
     const request = await body(ctx);
-    const actor = await authorize(ctx, "processes.manage", { processKey: key });
-    return await this.definitions.saveDraft(key, request.document, actor);
+    const { actor, request: from } = await callerOf(ctx, "workflow.processes.manage", { process: key });
+    const expected = optionalString(request.expected, "expected");
+    const expectedAt = expected === undefined ? undefined : new Date(expected);
+    if (expectedAt !== undefined && Number.isNaN(expectedAt.getTime())) throw new WorkflowError("invalid_input", "expected must be the draftUpdatedAt that was read");
+    return await this.definitions.saveDraft(key, request.document, actor, { request: from, ...(expectedAt === undefined ? {} : { expected: expectedAt }) });
   }
 
   @Post("processes/:key/publish")
+  @Authorize(can("workflow.processes.publish"))
   async publish(ctx: HttpContext) {
     const key = param(ctx, "key");
-    const actor = await authorize(ctx, "processes.publish", { processKey: key });
-    const version = await this.definitions.publish(key, actor);
+    const { actor, request } = await callerOf(ctx, "workflow.processes.publish", { process: key });
+    const version = await this.definitions.publish(key, actor, { request });
     return Created(`${ctx.path.replace(/\/publish$/, "")}/versions/${version.version}`, version);
   }
 
   @Get("processes/:key/versions")
+  @Authorize(can("workflow.processes.read"))
   async versions(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await authorize(ctx, "processes.read", { processKey: key });
+    await callerOf(ctx, "workflow.processes.read", { process: key });
     return { data: await this.definitions.versions(key) };
   }
 
   @Get("processes/:key/versions/:version")
+  @Authorize(can("workflow.processes.read"))
   async version(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await authorize(ctx, "processes.read", { processKey: key });
+    await callerOf(ctx, "workflow.processes.read", { process: key });
     const version = optionalInteger(param(ctx, "version"), "version");
     if (version === undefined) throw new WorkflowError("invalid_input", "version must be an integer");
     return await this.definitions.version(key, version);
   }
 
   @Get("tools")
-  async tools(ctx: HttpContext) {
-    await authorize(ctx, "processes.read");
+  @Authorize(can("workflow.processes.read"))
+  async tools() {
     return { data: this.definitions.tools() };
   }
 }

package/core/workflow/definitions_module/services/IWorkflowDefinitions.service.ts

@@ -1,6 +1,7 @@
+import type { AccessFilter } from "../../../access";
 import type { AgentToolContract } from "../../../agent";
 import type { ProcessDocument, ProcessIssue } from "../../../../library/workflow";
-import type { WorkflowActor, WorkflowPage, WorkflowPaging } from "../../contracts/types";
+import type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging } from "../../contracts/types";
 import type { OwnedCodeProcess } from "../code/codeProcesses";
 
 export interface ProcessSummary {
@@ -53,11 +54,25 @@ export interface UpdateProcess {
 }
 
 export interface ProcessListQuery extends WorkflowPaging {
+  /** Which processes the caller may see, from `IAccess`; without it the calling code has decided. */
+  readonly access?: AccessFilter;
   readonly archived?: boolean;
   /** Part of the key or title, case-insensitive. */
   readonly search?: string;
 }
 
+export interface SaveDraftOptions extends WorkflowAuditOptions {
+  /** The `draftUpdatedAt` the caller read: another save since then is `conflict`. Without it the last save wins. */
+  readonly expected?: Date;
+}
+
+export interface SavedDraft {
+  /** Every validation finding: a draft is stored with errors too. */
+  readonly issues: readonly ProcessIssue[];
+  /** Goes to `expected` of the next save. */
+  readonly draftUpdatedAt: Date;
+}
+
 /**
  * The process catalog: drafts and immutable published versions
  * (WORKFLOW-001 §3). Errors are {@link WorkflowError}: `not_found`, `conflict`,
@@ -66,16 +81,16 @@ export interface ProcessListQuery extends WorkflowPaging {
 export abstract class IWorkflowDefinitions {
   abstract list(query?: ProcessListQuery): Promise<WorkflowPage<ProcessSummary>>;
   abstract get(key: string): Promise<ProcessDetails>;
-  abstract create(process: CreateProcess, actor: WorkflowActor): Promise<ProcessDetails>;
+  abstract create(process: CreateProcess, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<ProcessDetails>;
   /** A process declared in code takes only `archived`; other fields give `conflict`. */
-  abstract update(key: string, changes: UpdateProcess, actor: WorkflowActor): Promise<ProcessDetails>;
-  /** Stores the draft even with errors and returns every validation finding; `conflict` for a process declared in code. */
-  abstract saveDraft(key: string, document: unknown, actor: WorkflowActor): Promise<{ readonly issues: readonly ProcessIssue[] }>;
+  abstract update(key: string, changes: UpdateProcess, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<ProcessDetails>;
+  /** Stores the draft even with errors; `conflict` for a process declared in code and when `expected` is out of date. */
+  abstract saveDraft(key: string, document: unknown, actor: WorkflowActor, options?: SaveDraftOptions): Promise<SavedDraft>;
   /**
    * Validates the draft and stores it as the next version; the same document
    * again returns the latest version. `conflict` for a process declared in code.
    */
-  abstract publish(key: string, actor: WorkflowActor): Promise<VersionDetails>;
+  abstract publish(key: string, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<VersionDetails>;
   abstract versions(key: string): Promise<readonly VersionSummary[]>;
   abstract version(key: string, version: number): Promise<VersionDetails>;
   /** The latest published version of a process that is not archived. */