anbaric-tsapi 1.18.1 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-tsapi",
-  "version": "1.18.1",
+  "version": "1.20.0",
   "description": "These are the shared libraries - types, classes, etc - that both the public state-machine and hosting services share",
   "license": "MIT",
   "author": "chris@anbaric.ai",

package/src/api/actions/Await.ts

@@ -0,0 +1,37 @@
+import {Job} from "../jobs/Job";
+import {AwaitParty, WaitForInput} from "./WaitForInput";
+
+/* A pause point in a state's action list. When a job reaches an Await it runs
+   nothing: the job is parked in the "Awaiting input" status and is not
+   re-enqueued until an update to its properties arrives (a human filling in a
+   form, say). An Await carries no actor - which actor eventually provides the
+   input is not known until it does. It describes what is being waited on
+   through the WaitForInput it assembles: the fields expected, a resolve URL
+   (static, or derived per job) and any extra metadata. That WaitForInput is
+   stored against the job and audited, and cleared once a transition moves the
+   job on to another state. */
+class Await {
+
+    readonly id : string;
+    name : string;
+    description : string;
+    waitingFor? : AwaitParty;
+    fields : Array<string> = [];
+    resolveUrl : string | ((job : Job) => string) = "";
+    metadata : (job : Job) => Map<string, any> = (_job : Job) => new Map();
+
+    constructor(name : string, waitingFor? : AwaitParty, description : string = "", id : string = crypto.randomUUID()) {
+        this.name = name;
+        this.waitingFor = waitingFor;
+        this.description = description;
+        this.id = id;
+    }
+
+    waitForInput(job : Job) : WaitForInput {
+        const resolveUrl = typeof this.resolveUrl === "function" ? this.resolveUrl(job) : this.resolveUrl;
+        return new WaitForInput(this.fields, resolveUrl, this.metadata(job), this.waitingFor);
+    }
+
+}
+
+export { Await }

package/src/api/actions/WaitForInput.ts

@@ -0,0 +1,43 @@
+type AwaitParty = "HUMAN" | "EXTERNAL_SYSTEM";
+
+/* What an Await is waiting for: which kind of party (a human or an external
+   system), the input fields it expects, a URL a client can send the user to in
+   order to provide them, and any extra metadata. A pure data class - it carries
+   no behaviour. */
+class WaitForInput {
+
+    fields : Array<string>;
+    resolveUrl : string;
+    metadataMap : Map<string, any>;
+    waitingFor? : AwaitParty;
+
+    constructor(fields : Array<string> = [], resolveUrl : string = "",
+                metadataMap : Map<string, any> = new Map(), waitingFor? : AwaitParty) {
+        this.fields = fields;
+        this.resolveUrl = resolveUrl;
+        this.metadataMap = metadataMap;
+        this.waitingFor = waitingFor;
+    }
+
+}
+
+type SerializedWaitForInput = {
+    fields : Array<string>,
+    resolveUrl : string,
+    metadataMap : Record<string, any>,
+    waitingFor? : AwaitParty,
+};
+
+const serializeWaitForInput = (wait : WaitForInput) : SerializedWaitForInput => ({
+    fields: wait.fields,
+    resolveUrl: wait.resolveUrl,
+    metadataMap: Object.fromEntries(wait.metadataMap),
+    waitingFor: wait.waitingFor,
+});
+
+const deserializeWaitForInput = (serialized : SerializedWaitForInput) : WaitForInput =>
+    new WaitForInput(serialized.fields ?? [], serialized.resolveUrl ?? "",
+        new Map(Object.entries(serialized.metadataMap ?? {})), serialized.waitingFor);
+
+export { WaitForInput, serializeWaitForInput, deserializeWaitForInput };
+export type { SerializedWaitForInput, AwaitParty };

package/src/api/actors/Actor.ts

@@ -4,7 +4,7 @@ interface Actor {
 
     type : ActorType;
     id : string;
-    role : string;
+    roles : Array<string>;
 
 }
 

package/src/api/actors/SystemActor.ts

@@ -4,7 +4,7 @@ class SystemActor implements Actor {
 
     type : ActorType = "SYSTEM";
     id = "_SYSTEM";
-    role = "_SYSTEM";
+    roles = ["_SYSTEM"];
 
     static actor = new SystemActor();
 

package/src/api/actors/agents/Agent.ts

@@ -8,12 +8,12 @@ class Agent implements Actor {
 
     readonly type = "AGENT" as const;
     readonly id : string;
-    readonly role : string;
+    readonly roles : Array<string>;
     readonly client : Agent.Client;
 
-    constructor(id : string, role : string, client : Agent.Client) {
+    constructor(id : string, roles : Array<string> | string, client : Agent.Client) {
         this.id = id;
-        this.role = role;
+        this.roles = typeof roles === "string" ? [roles] : roles;
         this.client = client;
     }
 

package/src/api/cloud/WorkflowDefinition.ts

@@ -1,7 +1,12 @@
+import {State} from "../states/State";
+import {PropertyDefinition} from "../jobs/PropertyDefinition";
+import {Await} from "../actions/Await";
+
 /* The serialisable graph of a state machine: its states, each state's actions
    (identity only — the run/predicate bodies aren't persistable) and
    transitions. Recorded as the details of an audit record when a state machine
-   initialises. */
+   initialises. Awaits are pause points rather than actors acting, so they are
+   not part of the graph - awaiting jobs are surfaced separately. */
 type WorkflowDefinition = {
 
     workflowId : string,
@@ -10,10 +15,33 @@ type WorkflowDefinition = {
     states : Array<{
         id : string,
         isTerminal : boolean,
-        actions : Array<{ name : string, description : string, actor : { id : string, type : string, role : string } }>,
+        actions : Array<{ name : string, description : string, actor : { id : string, type : string, roles : Array<string> } }>,
         transitions : Array<{ to : string }>,
     }>,
 
 };
 
-export type { WorkflowDefinition }
+namespace WorkflowDefinition {
+
+    export const describe = (workflowId : string, startState : string,
+                             states : Array<State>, dataSchema : Array<PropertyDefinition>) : WorkflowDefinition => ({
+        workflowId,
+        startState,
+        dataSchema: dataSchema.map(property => ({ id: property.id, required: property.required })),
+        states: states.map(state => ({
+            id: state.id,
+            isTerminal: state.isTerminal,
+            actions: state.actions
+                .filter((action) : action is Exclude<typeof action, Await> => ! (action instanceof Await))
+                .map(action => ({
+                    name: action.name,
+                    description: action.description,
+                    actor: { id: action.actor.id, type: action.actor.type, roles: action.actor.roles },
+                })),
+            transitions: state.transitions.map(transition => ({ to: transition.to })),
+        })),
+    });
+
+}
+
+export { WorkflowDefinition }

package/src/api/jobs/Job.ts

@@ -1,4 +1,4 @@
-import {Transition} from "../transitions/Transition";
+import {WaitForInput} from "../actions/WaitForInput";
 
 class Job {
 
@@ -10,10 +10,20 @@ class Job {
     readonly startedBy : string;
     readonly lastUpdated : Date;
     readonly killed : boolean;
+    // Distinct from state: the job's processing status. A job whose current
+    // state reaches an Await is parked in "Awaiting input" until an update
+    // resumes it. waitingFor is the id of the await it is parked on (a foreign
+    // key to the awaits table server-side); awaitMetadata is what that Await
+    // stored (e.g. the input required). Both clear once the job moves on.
+    status : string;
+    waitingFor? : string;
+    awaitMetadata? : WaitForInput;
 
     constructor(id : string, properties : Map<string, any> = new Map(), state: string, workflowId? : string,
                 startedBy : string = "system", startedAt : Date = new Date(),
-                lastUpdated : Date = startedAt, killed : boolean = false) {
+                lastUpdated : Date = startedAt, killed : boolean = false,
+                status : string = Job.Status.ACTIVE, awaitMetadata? : WaitForInput,
+                waitingFor? : string) {
 
         this.id = id;
         this.properties = properties;
@@ -23,8 +33,20 @@ class Job {
         this.startedAt = startedAt;
         this.lastUpdated = lastUpdated;
         this.killed = killed;
+        this.status = status;
+        this.awaitMetadata = awaitMetadata;
+        this.waitingFor = waitingFor;
     }
 
 }
 
+namespace Job {
+
+    export const Status = {
+        ACTIVE: "active",
+        AWAITING_INPUT: "Awaiting input",
+    } as const;
+
+}
+
 export { Job }

package/src/api/jobs/JobPersistence.ts

@@ -1,6 +1,7 @@
 import {Actor} from "../actors/Actor";
 import {Auditor} from "../auditing/Auditor";
 import {Job} from "./Job";
+import {serializeWaitForInput} from "../actions/WaitForInput";
 
 /* Persists jobs and audits every interaction. Public methods record the
    interaction against the injected auditor and then defer to the abstract
@@ -24,7 +25,7 @@ abstract class JobPersistence {
                properties? : Map<string, any>,
                state? : string) : Promise<void> {
 
-        const change = {
+        const change : { properties? : any, state? : any, metadata? : Record<string, any> } = {
             properties: properties ? this.generatePropertiesDiff(job.properties, properties) : undefined,
             state: state ? {from : job.state, to : state} : undefined
         }
@@ -32,6 +33,10 @@ abstract class JobPersistence {
         const interaction : Array<string> = [];
         if (properties) interaction.push(JobPersistence.Interaction.UPDATE_PROPERTIES);
         if (state) interaction.push(JobPersistence.Interaction.CHANGE_STATE);
+        if (job.status === Job.Status.AWAITING_INPUT && job.awaitMetadata) {
+            interaction.push(JobPersistence.Interaction.AWAIT);
+            change.metadata = serializeWaitForInput(job.awaitMetadata);
+        }
 
         await this.auditor.audit("job", job.id, actor, interaction, changeDescription, change);
 
@@ -43,7 +48,10 @@ abstract class JobPersistence {
             job.startedBy,
             job.startedAt,
             new Date(),
-            job.killed
+            job.killed,
+            job.status,
+            job.awaitMetadata,
+            job.waitingFor
         )
 
         this.saveInternal(updatedJob);
@@ -113,6 +121,7 @@ namespace JobPersistence {
         CREATE = "CREATE",
         UPDATE_PROPERTIES = "UPDATE_PROPERTIES",
         CHANGE_STATE = "CHANGE_STATE",
+        AWAIT = "AWAIT",
         DELETE = "DELETE",
         READ = "READ",
         LIST = "LIST",

package/src/api/jobs/JobSerialization.ts

@@ -1,4 +1,5 @@
 import {Job} from "./Job";
+import {SerializedWaitForInput, serializeWaitForInput, deserializeWaitForInput} from "../actions/WaitForInput";
 
 type SerializedJob = {
     id : string,
@@ -9,6 +10,9 @@ type SerializedJob = {
     startedBy? : string,
     lastUpdated? : string,
     killed? : boolean,
+    status? : string,
+    waitingFor? : string,
+    awaitMetadata? : SerializedWaitForInput,
 };
 
 const serializeJob = (job : Job) : SerializedJob => ({
@@ -20,13 +24,19 @@ const serializeJob = (job : Job) : SerializedJob => ({
     startedBy: job.startedBy,
     lastUpdated: job.lastUpdated.toISOString(),
     killed: job.killed,
+    status: job.status,
+    waitingFor: job.waitingFor,
+    awaitMetadata: job.awaitMetadata ? serializeWaitForInput(job.awaitMetadata) : undefined,
 });
 
 const deserializeJob = (serialized : SerializedJob) : Job => {
     const startedAt = serialized.startedAt ? new Date(serialized.startedAt) : new Date();
     return new Job(serialized.id, new Map(Object.entries(serialized.properties)), serialized.state,
         serialized.workflowId, serialized.startedBy ?? "system", startedAt,
-        serialized.lastUpdated ? new Date(serialized.lastUpdated) : startedAt, serialized.killed ?? false);
+        serialized.lastUpdated ? new Date(serialized.lastUpdated) : startedAt, serialized.killed ?? false,
+        serialized.status ?? Job.Status.ACTIVE,
+        serialized.awaitMetadata ? deserializeWaitForInput(serialized.awaitMetadata) : undefined,
+        serialized.waitingFor);
 };
 
 export { serializeJob, deserializeJob };

package/src/api/sessions/SessionResolver.ts

@@ -0,0 +1,20 @@
+/* The identity behind a platform session token, as resolved by the platform. */
+type ResolvedSession = {
+
+    id : string,
+    roles : Array<string>,
+    tenant? : string,
+
+};
+
+/* Resolves a platform session token (the anbaric_session cookie) into the
+   user's identity. A deployed app cannot verify the token itself - it is signed
+   with a platform-only secret - so the resolution is a call to the platform.
+   Returns undefined when the token is missing, invalid or expired. */
+interface SessionResolver {
+
+    resolve(sessionToken : string) : Promise<ResolvedSession | undefined>;
+
+}
+
+export type { SessionResolver, ResolvedSession }

package/src/api/states/State.ts

@@ -1,21 +1,22 @@
 import {Action} from "../actions/Action";
+import {Await} from "../actions/Await";
 import {Transition} from "../transitions/Transition";
 
 class State {
 
     readonly id : string;
-    actions : Array<Action>;
+    actions : Array<Action | Await>;
     transitions : Array<Transition>;
     readonly isTerminal : boolean;
 
-    constructor(id : string, actions : Array<Action> = [], transitions : Array<Transition> = [], isTerminal : boolean = false) {
+    constructor(id : string, actions : Array<Action | Await> = [], transitions : Array<Transition> = [], isTerminal : boolean = false) {
         this.id = id;
         this.actions = actions;
         this.transitions = transitions;
         this.isTerminal = isTerminal;
     }
 
-    subscribe(action : Action) : void {
+    subscribe(action : Action | Await) : void {
         this.actions.push(action);
     }
 

package/src/index.ts

@@ -5,6 +5,8 @@ export * from "./api/jobs/PropertyDefinition"
 export * from "./api/states/State"
 export * from "./api/states/Terminal"
 export * from "./api/actions/Action"
+export * from "./api/actions/Await"
+export * from "./api/actions/WaitForInput"
 export * from "./api/actions/AgenticAction"
 export * from "./api/actors/agents/AgentMessage"
 export * from "./api/actors/agents/AgentRequest"
@@ -14,6 +16,7 @@ export * from "./api/auditing/NoOpAuditor"
 export * from "./api/transitions/Transition"
 export * from "./api/actors/Actor"
 export * from "./api/actors/SystemActor"
+export * from "./api/sessions/SessionResolver"
 export * from "./api/documents/JsonStore"
 export * from "./api/secrets/SecretStore"
 export * from "./api/sql/SqlStore"