@arbidocs/blocks 0.4.75 → 0.4.77

package/dist/agents/workflows/types.d.ts

@@ -6,7 +6,9 @@
  * `workflowFromFrontmatter`), so the backend can adopt it without a UI change. Blocks hold no
  * domain wording: titles, labels and prompt text are data supplied by the host.
  */
-export type WorkflowFieldType = 'text' | 'longtext' | 'boolean' | 'select' | 'number' | 'date' | 'scope' | 'documents';
+export type WorkflowFieldType = 'text' | 'longtext' | 'boolean' | 'select' | 'number' | 'date' | 'scope' | 'documents'
+/** A workspace member (`usr-…` / `agt-…`): what a step's assignee or a signer can name. */
+ | 'person';
 /**
  * What a launching surface can hand a workflow without asking the user: the files it is looking at
  * (`documents`), the text the user selected (`selection`), or the image on screen (`image`, a file
@@ -92,6 +94,31 @@ export type WorkflowRun =
         y: number;
     }>;
 };
+/**
+ * When a step's signal is raised, tested against the step's outcome once it is done (a skipped or
+ * failed step never signals): a form field equals a value (case-insensitive text), the agent's
+ * answer contains a phrase or matches a regex, or a review is approved. Absent = whenever it is done.
+ */
+export type WorkflowSignalWhen = {
+    field: string;
+    equals: string | number | boolean;
+} | {
+    contains: string;
+} | {
+    matches: string;
+} | {
+    approved: true;
+};
+/**
+ * A named signal a step raises when it is done and its condition holds. Another workflow starts on
+ * it ("When a step signals") as its own thread linked to this one, so the if/then between
+ * workflows lives in the link and each workflow stays short.
+ */
+export interface WorkflowSignal {
+    /** A slug (`[a-z0-9][a-z0-9_.-]*`), e.g. `risk-high`: what a linked workflow listens for. */
+    name: string;
+    when?: WorkflowSignalWhen;
+}
 interface WorkflowStepBase {
     /** Unique within the workflow (`[a-z][a-z0-9_-]*`): the thread's progress is keyed by it. */
     id: string;
@@ -113,7 +140,76 @@ interface WorkflowStepBase {
      * sequence. `[]`: it starts with the run. A step waiting for several waits for them all.
      */
     after?: string[];
+    /** Signals the step raises when it is done and their condition holds. */
+    signals?: WorkflowSignal[];
+    /**
+     * Who the step is for (a person step, or a signature or email step): they are told when it is
+     * ready, and only they (or the run's owner) can do it. Absent: whoever is on the run.
+     */
+    assignee?: WorkflowAssignee;
+    /** A person step left this many hours is announced again (once). */
+    remindAfterHours?: number;
+}
+/**
+ * Who a step is for: a named member (`usr-…` / `agt-…`), whoever started the run, the person a
+ * form's `person` field names (`input`: its name), or the project's lead.
+ */
+export type WorkflowAssignee = {
+    user: string;
+} | {
+    runOwner: true;
+} | {
+    input: string;
+} | {
+    projectLead: true;
+};
+/**
+ * A document a step works on, named by where it comes from: what an earlier step produced or was
+ * given (an upload's files, an agent's draft, a signed copy, an edited version), what a run input
+ * names (a document pick), or one document by id (`doc-…`, optionally `@v<n>`).
+ */
+export type WorkflowDocumentRef = {
+    step: string;
+} | {
+    input: string;
+} | {
+    id: string;
+};
+/** Ask people to e-sign a document. The step waits until every signer has signed. */
+export interface WorkflowSignAction {
+    type: 'sign';
+    document?: WorkflowDocumentRef;
+    signers: WorkflowAssignee[];
+    /** Shown to the signers. */
+    message?: string;
+    /** Unsigned this long after it starts, the step fails. */
+    expiresAfterHours?: number;
+}
+/**
+ * Prepare an email in native mail, never sent by itself: its person sends it, and the step is done
+ * when they say so (or send it). Every text is a template over the run (`{{field}}`,
+ * `{{step.answer}}`).
+ */
+export interface WorkflowEmailDraftAction {
+    type: 'email_draft';
+    to: string[];
+    cc?: string[];
+    subject: string;
+    body: string;
+    attachments?: WorkflowDocumentRef[];
+}
+/** Run review columns (labels with instructions) over documents, then open the grid. */
+export interface WorkflowTabularReviewAction {
+    type: 'tabular_review';
+    /** Label (tag) ids: the columns. */
+    tags: string[];
+    /** Every file the run's uploads took, every document of the workspace, or these documents. */
+    documents: 'run_uploads' | 'workspace' | WorkflowDocumentRef[];
+    /** Fill cells that already have a value again. */
+    overwrite?: boolean;
 }
+export type WorkflowAction = WorkflowSignAction | WorkflowEmailDraftAction | WorkflowTabularReviewAction;
+export type WorkflowActionType = WorkflowAction['type'];
 /** Ask for inputs. Every step's fields share the run's one input namespace (`{{name}}`). */
 export interface WorkflowFormStep extends WorkflowStepBase {
     kind: 'form';
@@ -153,14 +249,29 @@ export interface WorkflowAgentStep extends WorkflowStepBase {
     output?: 'answer' | 'artifact';
     /** Runs off the thread's main line and delivers only its result to it. */
     branch?: boolean;
+    /**
+     * Edit this Word document with tracked changes (the instruction says what to change); the
+     * edited copy is its next version, to accept or reject change by change. Main line only.
+     */
+    editDocument?: WorkflowDocumentRef;
 }
 /** A person's review or approval: whoever completes it on the thread approves it. */
 export interface WorkflowReviewStep extends WorkflowStepBase {
     kind: 'review';
     /** What to review, a template over the run's inputs. */
     instructions?: string;
+    /** What the approver fills in when approving (e.g. a rating): they join the run's inputs. */
+    fields?: WorkflowField[];
 }
-export type WorkflowStep = WorkflowFormStep | WorkflowUploadStep | WorkflowAgentStep | WorkflowReviewStep;
+/**
+ * A step that uses a platform feature rather than producing text: an e-signature, an email draft
+ * or a tabular review. It starts by itself; a signature and an email then wait for their people.
+ */
+export interface WorkflowActionStep extends WorkflowStepBase {
+    kind: 'action';
+    action: WorkflowAction;
+}
+export type WorkflowStep = WorkflowFormStep | WorkflowUploadStep | WorkflowAgentStep | WorkflowReviewStep | WorkflowActionStep;
 /** The finish screen of a stepped run. */
 export interface WorkflowCompletion {
     title: string;
@@ -169,9 +280,33 @@ export interface WorkflowCompletion {
 }
 /**
  * Where a step of a run is, as the thread records it: not reached yet (`pending`), `running`,
- * `done`, `skipped`, or `failed` (it can be retried or skipped).
+ * `waiting` (an action step waiting on its signers or on its email being sent), `done`,
+ * `skipped`, or `failed` (it can be retried or skipped).
  */
-export type WorkflowStepStatus = 'pending' | 'running' | 'done' | 'skipped' | 'failed';
+export type WorkflowStepStatus = 'pending' | 'running' | 'waiting' | 'done' | 'skipped' | 'failed';
+/** What an action step waits on (ids only), as its latest event says. */
+export interface WorkflowActionWaiting {
+    /** A signature: the document and version to sign, who signs, who has signed. */
+    doc_ext_id?: string;
+    version?: number;
+    signers?: string[];
+    signed?: string[];
+    expires_at?: string;
+    /** An email: the draft in native mail and whose mailbox it is in. */
+    draft_id?: string;
+    mailbox?: string;
+    [key: string]: unknown;
+}
+/** What a review recorded it approved: each step it waited for, as it stood then. */
+export interface WorkflowApprovalEvidence {
+    step: string;
+    status: string;
+    /** That step's answer (a message in the thread). */
+    response_id?: string;
+    /** The document versions it had (`doc-…@v<n>`). */
+    documents?: string[];
+    output?: Record<string, unknown>;
+}
 export interface WorkflowStepState {
     status: WorkflowStepStatus;
     /** The step's answer in the thread (an agent step), or the result a branch delivered. */
@@ -181,6 +316,27 @@ export interface WorkflowStepState {
     error?: string | null;
     /** When it started running (ISO), for the elapsed time while it runs. */
     startedAt?: string;
+    /** An action step's type, once it has started. */
+    action?: WorkflowActionType;
+    /** What a `waiting` action step waits on. */
+    waiting?: WorkflowActionWaiting;
+    /** What a done action step produced (ids: the signed version, the draft, the reviewed labels). */
+    output?: Record<string, unknown>;
+    /** The document versions the step produced or was given (`doc-…@v<n>`). */
+    documents?: string[];
+    /** Reopened by a send-back to this step and not touched since (`hasNote`: with a note). */
+    sentBack?: boolean;
+    hasNote?: boolean;
+    /** Who was told the step is ready (`usr-…` / `agt-…`), since it last changed. */
+    announcedTo?: string | null;
+    /** Who finished it (completed, approved, skipped, declined). */
+    by?: string | null;
+    /** When it finished (ISO). */
+    at?: string;
+    /** A review: what it approved. */
+    approved?: WorkflowApprovalEvidence[];
+    /** A declined signature: who declined. */
+    declinedBy?: string;
 }
 export interface WorkflowDefinition {
     /** Execute a document operation directly, without creating a chat. */

package/dist/agents/workflows/useWorkflowPreview.d.ts

@@ -1,6 +1,7 @@
 /**
  * A stepped workflow run on screen only (the builder's preview): agent steps run one at a time,
- * the way the server does, and answer with the prompt they would send. No thread, no agent.
+ * the way the server does, and answer with the prompt they would send; action steps just finish.
+ * No thread, no agent.
  */
 import { type StepComposeOptions } from './run';
 import type { WorkflowDefinition } from './types';

package/dist/agents/workflows/useWorkflowView.d.ts

@@ -20,6 +20,17 @@ export interface UseWorkflowViewOptions {
     retry?: (stepId: string) => Promise<void>;
     /** A form step whose inputs can no longer change (committed, or recorded on the thread). */
     isLocked?: (stepId: string) => boolean;
+    /**
+     * Whether `states` are known yet (a run opened later: its thread's log has arrived). Until then
+     * the view waits to open the run where it is, instead of at its first step. Default true.
+     */
+    loaded?: boolean;
+    /** Send the work back from a ready step to an earlier one, with a note. */
+    sendBack?: (stepId: string, to: string, note?: string) => Promise<void>;
+    /** A signer refuses a signature step, with a note. */
+    decline?: (stepId: string, note?: string) => Promise<void>;
+    /** A member's name by id (`usr-…` / `agt-…`): assignees and signers are shown by name. */
+    nameOf?: (id: string) => string | undefined;
 }
 /** What `WorkflowRunner` shows and does. */
 export interface WorkflowRunView {
@@ -48,6 +59,14 @@ export interface WorkflowRunView {
     goTo: (stepId: string) => void;
     skip: (stepId: string) => Promise<void>;
     retry?: (stepId: string) => Promise<void>;
+    /** Send the work back from `stepId` to `to` (it is then in view). Absent = not offered. */
+    sendBack?: (stepId: string, to: string, note?: string) => Promise<void>;
+    /** Decline a signature step. Absent = not offered. */
+    decline?: (stepId: string, note?: string) => Promise<void>;
+    /** A member's name by id. */
+    nameOf?: (id: string) => string | undefined;
+    /** Who a step is for, in words (a person step, a signature, an email), if anyone. */
+    assigneeOf: (stepId: string) => string | undefined;
     /** Show the run from the start again (a host that starts a new run resets its own state). */
     restart: () => void;
 }

package/dist/chat/ChatPage.d.ts

@@ -16,4 +16,4 @@ import { type ChatPageProps } from './chat-page-types';
  * With `surface="page"` it claims the page-chat slot, so `useChatSurface()` tells the host's dock
  * to yield: one chat on screen, never two.
  */
-export declare function ChatPage({ chat, surface, header, headerActions, aside, prompts, documentsRequired, emptyTitle, emptyDescription, identity, renderContent, onOpenCitation, targetMessageId, asideBreakpoint, fillHeight, minHeight, compactHeader, accept, labels, className, testIds, }: ChatPageProps): import("react").JSX.Element;
+export declare function ChatPage({ chat, surface, header, headerActions, aside, prompts, documentsRequired, emptyTitle, emptyDescription, identity, renderContent, onOpenCitation, workflowStepTitle, targetMessageId, asideBreakpoint, fillHeight, minHeight, compactHeader, accept, labels, className, testIds, }: ChatPageProps): import("react").JSX.Element;

package/dist/chat/WorkflowStepChip.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A message the server sent to start a workflow's step, shown as that step: a compact chip
+ * ("Workflow step · Draft the letter") that expands to the full instruction. Any chat that knows a
+ * message's step (its `tools.workflow_step`) renders this instead of the raw instruction.
+ */
+export interface WorkflowStepChipLabels {
+    /** `{title}` is the step's title (its id when the title is not known). */
+    chip: string;
+    show: string;
+    hide: string;
+}
+export declare const DEFAULT_WORKFLOW_STEP_CHIP_LABELS: WorkflowStepChipLabels;
+export interface WorkflowStepChipProps {
+    /** The step's id. */
+    step: string;
+    /** The step's title, when the host knows it (from the run's plan). */
+    title?: string;
+    /** The instruction the step sent. */
+    content: string;
+    labels?: Partial<WorkflowStepChipLabels>;
+    className?: string;
+    testId?: string;
+}
+export declare function WorkflowStepChip({ step, title, content, labels, className, testId, }: WorkflowStepChipProps): import("react").JSX.Element;

package/dist/chat/chat-page-types.d.ts

@@ -47,6 +47,8 @@ export interface ChatPageMessage {
     citations?: ReadonlyArray<ChatPageCitation>;
     /** The reader stopped the answer; `content` is what had streamed. */
     stopped?: boolean;
+    /** A user message that started a workflow step (its id): shown as that step's chip. */
+    workflowStep?: string;
 }
 export interface ChatPageThread {
     id: string;
@@ -175,6 +177,8 @@ export interface ChatPageProps {
      * shows the source and passage and offers no open action.
      */
     onOpenCitation?: (target: ChatCitationTarget) => void;
+    /** A workflow step's title by id: a message that started a step shows it (else the id). */
+    workflowStepTitle?: (stepId: string) => string | undefined;
     /**
      * Container width, in rem, from which `aside` is a column beside the chat; narrower, it is a
      * button-toggled panel over the transcript. Default 60.