anbaric-state-machine 1.7.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-state-machine",
-  "version": "1.7.0",
+  "version": "2.0.0",
   "description": "This is the state machine library that one can use to add state management to an application. It will, by default, be locally runnable but can deployed to the Anbaric Cloud via the CLI",
   "license": "MIT",
   "author": "chris@anbaric.ai",
@@ -15,8 +15,8 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "anbaric-impl-cloud": "^1.7.0",
-    "anbaric-tsapi": "^1.7.0"
+    "anbaric-impl-cloud": "^2.0.0",
+    "anbaric-tsapi": "^2.0.0"
   },
   "files": [
     "src"

package/src/StateMachine.ts

@@ -1,10 +1,18 @@
-import {Action, Actor, Auditor, Consumer, Job, JobPersistence, PropertyDefinition, Queue, State} from "anbaric-tsapi";
+import {
+    Action,
+    Actor,
+    AuditInteraction,
+    Consumer,
+    Job,
+    JobPersistence,
+    PropertyDefinition,
+    Queue,
+    State
+} from "anbaric-tsapi";
 import {JobPersistenceFactory} from "./persistence/JobPersistenceFactory";
 import {QueueFactory} from "./scheduling/QueueFactory";
 import {ConsumerFactory} from "./scheduling/ConsumerFactory";
 import {Code} from "./actors/Code";
-import {AuditorFactory} from "./auditing/AuditorFactory";
-import {AuditorTransaction} from "./auditing/AuditorTransaction";
 
 class StateMachine {
 
@@ -15,10 +23,9 @@ class StateMachine {
     private persistence: JobPersistence;
     private queue: Queue;
     private consumer: Consumer;
-    private auditor: Auditor;
     private machineActor: Code;
 
-    constructor(workflowId : string, states : Array<State>, startState : string, dataSchema : Array<PropertyDefinition>, persistence : JobPersistence = JobPersistenceFactory.instance(), queue : Queue = QueueFactory.instance(), auditor : Auditor = AuditorFactory.instance()) {
+    constructor(workflowId : string, states : Array<State>, startState : string, dataSchema : Array<PropertyDefinition>, persistence : JobPersistence = JobPersistenceFactory.instance(), queue : Queue = QueueFactory.instance()) {
 
         this.workflowId = workflowId;
         this.states = new Map(states.map(state => [state.id, state]));
@@ -26,29 +33,21 @@ class StateMachine {
         this.dataSchema = new Map(dataSchema.map(property => [property.id, property]));
         this.persistence = persistence;
         this.queue = queue;
-        this.auditor = auditor;
         this.machineActor = new Code(workflowId, "state-machine");
 
         this.consumer = ConsumerFactory.instance(queue)
         this.consumer.subscribe(workflowId, jobId => this.progressJob(jobId));
     }
 
-    async startJob(properties?: Map<string, any>, actor? : Actor): Promise<Job> {
+    async startJob(properties?: Map<string, any>, actor : Actor = this.machineActor): Promise<Job> {
 
         const job = new Job(crypto.randomUUID(), properties, this.startState, this.workflowId,
             actor?.id ?? this.workflowId);
 
         if (! this.validateProperties(properties ?? new Map(), true)) throw new Error("Invalid properties");
+        if (! this.authorizeActor(actor, job)) throw new Error("Unauthorized");
 
-        if (! this.authorizeActor(actor, job)) {
-            await this.auditor.audit(job.id, actor ?? this.machineActor, "CREATE", "Unauthorized start", null);
-            throw new Error("Unauthorized");
-        }
-
-        await this.persistence.save(job);
-        await this.auditor.audit(job.id, actor ?? this.machineActor, "CREATE", "Job started",
-            Object.fromEntries(job.properties));
-
+        await this.persistence.create(actor, job);
         await this.queue.enqueue(job.id, this.workflowId);
 
         return job;
@@ -56,40 +55,35 @@ class StateMachine {
 
     async updateJob(jobId : string, properties : Map<string, any>, actor : Actor) : Promise<void> {
 
-        if (! this.authorizeActor(actor, await this.persistence.retrieve(jobId))) {
-            await this.auditor.audit(jobId, actor, "UPDATE_PROPERTIES", "Unauthorized update", null);
-            throw new Error("Unauthorized");
-        }
-
-        if (! this.validateProperties(properties, false)) throw new Error("Invalid properties");
+        const job = await this.persistence.retrieve(jobId, actor);
 
-        await this.persistence.updateProperties(jobId, properties);
-        await this.auditor.audit(jobId, actor, "UPDATE_PROPERTIES", "Properties updated", Object.fromEntries(properties));
+        if (!this.authorizeActor(actor, job)) throw new Error("Unauthorized");
 
-        await this.queue.enqueue(jobId, this.workflowId);
+        await this.updateJobInternal(actor, "Properties Updated", job, properties);
     }
 
     async executeAction(jobId : string, action : Action) : Promise<void> {
-        const job = await this.persistence.retrieve(jobId);
 
-        if (! action.predicate(job)) throw new Error("Action predicate unmet");
+        const job = await this.persistence.retrieve(jobId, action.actor);
 
-        if (! this.authorizeActor(action.actor, job)) {
-            await this.auditor.audit(jobId, action.actor, "UPDATE_PROPERTIES", "Unauthorized update", null);
-            throw new Error("Actor not authorized to execute action");
-        }
+        if (! action.predicate(job)) throw new Error("Action predicate unmet");
+        if (! this.authorizeActor(action.actor, job)) throw new Error("Actor not authorized to execute action");
 
         const newProperties = await action.run(job);
 
-        if (! this.validateProperties(newProperties, false)) {
-            await this.auditor.audit(jobId, action.actor, "UPDATE_PROPERTIES", "Invalid properties", Object.fromEntries(newProperties));
-            throw new Error("The action generated invalid properties");
+        try {
+            await this.updateJobInternal(action.actor, `Action ${action.name} executed on job ${job.id}: ${action.description}`, job, newProperties);
+        } catch (error) {
+            throw new Error('The action generated invalid properties');
         }
+    }
 
-        await this.persistence.updateProperties(jobId, newProperties);
-        await this.auditor.audit(jobId, action.actor, "UPDATE_PROPERTIES", "Properties updated", Object.fromEntries(newProperties));
+    private async updateJobInternal(actor: Actor, message : string, job: Job, newProperties?: Map<string, any>, newState? : string) {
 
-        await this.queue.enqueue(jobId, this.workflowId);
+        if (newProperties && !this.validateProperties(newProperties, false)) throw new Error("Invalid properties");
+
+        await this.persistence.save(actor, "Properties Updated", job, newProperties, newState)
+        await this.queue.enqueue(job.id, this.workflowId);
     }
 
     private validateProperties(properties : Map<string, any>, isNew : boolean) : boolean {
@@ -108,49 +102,44 @@ class StateMachine {
     }
 
     private async progressJob(jobId : string) : Promise<void> {
-        const auditTransaction = new AuditorTransaction(this.auditor);
         let pristine = true;
 
-        const job = await this.persistence.retrieve(jobId);
-        const currentState = this.states.get(job.stateId!);
+        const job = await this.persistence.retrieve(jobId, this.machineActor);
+        const currentState = this.states.get(job.state);
+
+        const involvedActors : Actor[] = [];
 
         for (const action of currentState?.actions ?? []) {
             if (! action.predicate(job)) continue;
-
-            if (! this.authorizeActor(action.actor, job)) {
-                auditTransaction.audit(jobId, action.actor, "UPDATE_PROPERTIES", "Unauthorized update", null);
-                continue;
-            }
+            if (! this.authorizeActor(action.actor, job)) continue;
 
             const newProperties = await action.run(job);
 
-            if (! this.validateProperties(newProperties, false)) {
-                auditTransaction.audit(jobId, action.actor, "UPDATE_PROPERTIES", "Invalid properties", Object.fromEntries(newProperties));
-                continue;
-            }
+            if (! this.validateProperties(newProperties, false)) continue;
+
+            involvedActors.push(action.actor);
 
-            auditTransaction.audit(jobId, action.actor, "UPDATE_PROPERTIES", "Properties updated", Object.fromEntries(newProperties));
             newProperties.forEach((value, key) => {
                 pristine = false;
                 job.properties.set(key, value);
             });
         }
 
+        let newState : string | undefined = undefined;
         for (const transition of currentState?.transitions ?? []) {
             if (! this.states.has(transition.to)) continue;
-            if (job.transition(transition)) {
-                auditTransaction.audit(jobId, this.machineActor, "CHANGE_STATE", `Transitioned to "${transition.to}"`, null);
+            if (transition.predicate(job)) {
+                newState = transition.to;
                 pristine = false;
                 break;
             }
         }
 
         if (! pristine) {
-            await this.persistence.save(job);
+            // TODO: persistence.save should have the ability to accept multiple actors for this case.
+            await this.persistence.save(involvedActors[0] ?? this.machineActor, `Job ${job.id} progressed automatically`, job, job.properties, newState);
             await this.queue.enqueue(job.id, this.workflowId);
         }
-
-        await auditTransaction.flush();
     }
 
     async cleanUp() : Promise<void> {

package/src/actions/RemoteLLMAgenticAction.ts

@@ -0,0 +1,27 @@
+import {Agent, AgenticAction, AgentMessage, AgentRequest, Job} from "anbaric-tsapi";
+
+/* An OpenAI-API-compatible agentic action: it carries a prompt as an array of
+   chat messages and a JSON Schema, appends the job's properties as the final
+   user message, and lets its agent's client generate the properties to write. */
+class RemoteLLMAgenticAction extends AgenticAction {
+
+    private messages : Array<AgentMessage>;
+    private outputSchema : object;
+
+    constructor(name : string, agent : Agent, messages : Array<AgentMessage>, outputSchema : object,
+                description : string = "", id? : string) {
+        super(name, agent, description, id);
+        this.messages = messages;
+        this.outputSchema = outputSchema;
+    }
+
+    protected requestFor(job : Job) : AgentRequest {
+        return {
+            messages: [...this.messages, { role: "user", content: JSON.stringify(Object.fromEntries(job.properties)) }],
+            outputSchema: this.outputSchema,
+        };
+    }
+
+}
+
+export { RemoteLLMAgenticAction }

package/src/agents/OpenAIAgent.ts

@@ -0,0 +1,83 @@
+import {Agent, AgentRequest} from "anbaric-tsapi";
+
+type FetchFn = (url : string, init : RequestInit) => Promise<Response>;
+
+type OpenAIConnection = {
+    apiKey : string,
+    model : string,
+    baseUrl? : string,
+    organization? : string,
+};
+
+const strictSchema = (schema : any) : any => {
+    if (schema?.type === "object" && schema.properties) {
+        return {
+            ...schema,
+            required: Object.keys(schema.properties),
+            additionalProperties: false,
+            properties: Object.fromEntries(
+                Object.entries(schema.properties).map(([key, property]) => [key, strictSchema(property)])),
+        };
+    }
+    if (schema?.type === "array" && schema.items) {
+        return { ...schema, items: strictSchema(schema.items) };
+    }
+    return schema;
+};
+
+/* The functional half of an OpenAI agent: asks an OpenAI-compatible chat
+   completions endpoint for JSON conforming to the request's schema via
+   structured outputs. */
+class OpenAIClient extends Agent.Client {
+
+    private baseUrl : string;
+
+    constructor(private connection : OpenAIConnection,
+                private fetchFn : FetchFn = (url, init) => fetch(url, init)) {
+        super();
+        this.baseUrl = connection.baseUrl ?? "https://api.openai.com/v1";
+    }
+
+    async generate(request : AgentRequest) : Promise<Record<string, any>> {
+        const response = await this.fetchFn(`${this.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "authorization": `Bearer ${this.connection.apiKey}`,
+                ...(this.connection.organization ? { "openai-organization": this.connection.organization } : {}),
+            },
+            body: JSON.stringify({
+                model: this.connection.model,
+                messages: request.messages,
+                response_format: {
+                    type: "json_schema",
+                    json_schema: { name: "properties", strict: true, schema: strictSchema(request.outputSchema) },
+                },
+            }),
+        });
+
+        if (!response.ok) {
+            const problem = await response.json().catch(() => ({}));
+            throw new Error(`The OpenAI request failed with status ${response.status}${problem.error?.message ? `: ${problem.error.message}` : ""}`);
+        }
+
+        const body = await response.json();
+        const content = body.choices?.[0]?.message?.content;
+        if (typeof content !== "string") throw new Error("The OpenAI response carried no structured content");
+        return JSON.parse(content);
+    }
+
+}
+
+/* A light agent backed by an OpenAI-compatible chat completions endpoint. */
+class OpenAIAgent extends Agent {
+
+    constructor(id : string, role : string, connection : OpenAIConnection,
+                fetchFn : FetchFn = (url, init) => fetch(url, init)) {
+        super(id, role, new OpenAIClient(connection, fetchFn));
+    }
+
+}
+
+export { OpenAIAgent, OpenAIClient }
+export type { OpenAIConnection }

package/src/auditing/ConsoleAuditor.ts

@@ -1,10 +1,10 @@
-import {Actor, AuditChange, Auditor} from "anbaric-tsapi";
+import {Actor, AuditInteraction, Auditor} from "anbaric-tsapi";
 
 class ConsoleAuditor implements Auditor {
 
-    async audit(jobId : string, actor : Actor, change : AuditChange,
-                changeDescription : string, details : any) : Promise<void> {
-        console.log(`[${jobId}] ${actor.id} ${change} ${changeDescription} ${JSON.stringify(details ?? null)}`);
+    async audit(resourceType : string, resourceId : string, actor : Actor, interaction : AuditInteraction[],
+                description : string, details : any) : Promise<void> {
+        console.log(`[${resourceType} ${resourceId}] ${actor.id} ${interaction.join(",")} ${description} ${JSON.stringify(details ?? null)}`);
     }
 
 }

package/src/index.ts

@@ -1,9 +1,9 @@
 export * from "./StateMachine";
-export * from "./actors/Agent";
+export * from "./actions/RemoteLLMAgenticAction";
+export * from "./agents/OpenAIAgent";
 export * from "./actors/Code";
 export * from "./actors/Human";
 export * from "./auditing/AuditorFactory";
-export * from "./auditing/AuditorTransaction";
 export * from "./auditing/ConsoleAuditor";
 export * from "./persistence/InMemoryJobPersistence";
 export * from "./persistence/JobPersistenceFactory";

package/src/persistence/InMemoryJobPersistence.ts

@@ -1,14 +1,18 @@
-import {Job, JobPersistence} from "anbaric-tsapi";
+import {Auditor, Job, JobPersistence, NoOpAuditor} from "anbaric-tsapi";
 
-class InMemoryJobPersistence implements JobPersistence {
+class InMemoryJobPersistence extends JobPersistence {
 
     private jobs = new Map<string, Job>();
 
-    async save(job : Job) : Promise<void> {
+    constructor(auditor : Auditor = new NoOpAuditor()) {
+        super(auditor);
+    }
+
+    protected async saveInternal(job : Job) : Promise<void> {
         this.jobs.set(job.id, job);
     }
 
-    async retrieve(id : string) : Promise<Job> {
+    protected async retrieveInternal(id : string) : Promise<Job> {
         const job = this.jobs.get(id);
         if (!job) {
             throw new Error(`No job found with id "${id}"`);
@@ -16,22 +20,14 @@ class InMemoryJobPersistence implements JobPersistence {
         return job;
     }
 
-    async delete(id : string) : Promise<void> {
+    protected async deleteInternal(id : string) : Promise<void> {
         this.jobs.delete(id);
     }
 
-    async list(pageSize : number = 100, page : number = 0) : Promise<Array<Job>> {
+    protected async listInternal(pageSize : number = 100, page : number = 0) : Promise<Array<Job>> {
         return Array.from(this.jobs.values()).slice(page * pageSize, (page + 1) * pageSize);
     }
 
-    async updateProperties(id : string, properties : Map<string, any>) : Promise<void> {
-        const job = await this.retrieve(id);
-        for (const [key, value] of properties) {
-            job.properties.set(key, value);
-        }
-        job.lastUpdated = new Date();
-    }
-
 }
 
 export { InMemoryJobPersistence }

package/src/persistence/JobPersistenceFactory.ts

@@ -1,15 +1,17 @@
 import {JobPersistence} from "anbaric-tsapi";
 import {CloudJobPersistence} from "anbaric-impl-cloud";
 import {InMemoryJobPersistence} from "./InMemoryJobPersistence";
+import {AuditorFactory} from "../auditing/AuditorFactory";
 
 const JobPersistenceFactory = {
     instance() : JobPersistence {
+        const auditor = AuditorFactory.instance();
         switch (process.env.ANBARIC_JOB_PERSISTENCE_TYPE) {
             case "cloud":
-                return new CloudJobPersistence();
+                return new CloudJobPersistence(undefined, auditor);
             case "memory":
             default:
-                return new InMemoryJobPersistence();
+                return new InMemoryJobPersistence(auditor);
         }
     }
 }

package/src/actors/Agent.ts

@@ -1,16 +0,0 @@
-import {Actor} from "anbaric-tsapi";
-
-class Agent implements Actor {
-
-    readonly type = "AGENT" as const;
-    readonly id : string;
-    readonly role : string;
-
-    constructor(id : string, role : string) {
-        this.id = id;
-        this.role = role;
-    }
-
-}
-
-export { Agent }

package/src/auditing/AuditorTransaction.ts

@@ -1,31 +0,0 @@
-import {Actor, AuditChange, Auditor} from "anbaric-tsapi";
-
-type BufferedEntry = {
-    jobId : string,
-    actor : Actor,
-    change : AuditChange,
-    changeDescription : string,
-    details : any,
-};
-
-class AuditorTransaction {
-
-    private entries = new Array<BufferedEntry>();
-
-    constructor(private auditor : Auditor) {}
-
-    audit(jobId : string, actor : Actor, change : AuditChange, changeDescription : string, details : any) : void {
-        this.entries.push({ jobId, actor, change, changeDescription, details });
-    }
-
-    async flush() : Promise<void> {
-        const flushing = this.entries;
-        this.entries = [];
-        for (const entry of flushing) {
-            await this.auditor.audit(entry.jobId, entry.actor, entry.change, entry.changeDescription, entry.details);
-        }
-    }
-
-}
-
-export { AuditorTransaction }