anbaric-tsapi 1.7.0 → 1.8.1

package/README.md

@@ -11,12 +11,10 @@ synchronous.
 
 ## Value classes
 
-**`Job`** — a unit of work moving through a workflow.
-`new Job(id, properties = new Map(), initialState, workflowId?, startedBy = "system", startedAt = new Date(), lastUpdated = startedAt, transitions = [])`.
-`stateId` is a getter; state only changes through
-`transition(transition, actor = workflowId ?? "state-machine")`, which
-records `{from, to, actor}` into `transitions` and bumps `lastUpdated` when
-the transition's predicate accepts the job.
+**`Job`** — a unit of work moving through a workflow. Immutable.
+`new Job(id, properties = new Map(), state, workflowId?, startedBy = "system", startedAt = new Date(), lastUpdated = startedAt)`.
+`state` is a readonly string; a job never changes in place — `JobPersistence.save`
+constructs a new `Job` at the target `state` and stamps `lastUpdated`.
 
 **`State`** — `new State(id, actions = [], transitions = [])`, plus
 `subscribe(action)` to add an action later.
@@ -27,7 +25,7 @@ accept) gates whether the action runs, and
 `run : (job) => Promise<Map<string, any>>` (defaults to an empty map)
 returns the property changes the action wants. `run` never mutates the job.
 
-**`Actor`** — an interface, pure identity: `{ type : "HUMAN" | "CODE" | "AGENT", id : string, role : string }`.
+**`Actor`** — an interface, pure identity: `{ type : "HUMAN" | "CODE" | "AGENT" | "SYSTEM", id : string, role : string }`.
 Concrete `Human`, `Code`, `Agent` classes live in `anbaric-state-machine`.
 
 **`Transition`** — `new Transition(to, predicate)`; the first accepting
@@ -37,18 +35,18 @@ transition in a state wins.
 `required : boolean` (default false) and `validation : (value) => boolean`
 (default accept).
 
-**`JobTransition`** — `{ from : string, to : string, actor : string }`.
-
 **Serialization** — `serializeJob(job) : SerializedJob` and
 `deserializeJob(serialized) : Job` define the wire shape used by the cloud
 clients and platform (dates as ISO strings, properties as a plain object).
 
 ## Contracts
 
-**`JobPersistence`** — `save(job)`, `retrieve(id)` (throws
-`No job found with id "x"`), `delete(id)`, `list(pageSize = 100, page = 0)`,
-`updateProperties(id, properties)` (merge; implementations stamp
-`lastUpdated`).
+**`JobPersistence`** — an abstract class taking an `Auditor`; every method takes
+the acting `Actor` and audits before deferring to an abstract `…Internal`.
+`create(actor, job)`, `save(actor, changeDescription, job, properties?, state?)`
+(applies the property/state change and stamps `lastUpdated`),
+`retrieve(id, actor)` (throws `No job found with id "x"`), `delete(id, actor)`,
+`list(actor, pageSize?, page?)`.
 
 **`Queue`** — `enqueue(jobId, workflowId)`, `schedule(jobId, workflowId, due)`.
 **`Dequeue extends Queue`** adds `dequeueSome() : Promise<Array<QueueMessage>>`;
@@ -58,10 +56,15 @@ Delivery is at-least-once: consumers must tolerate redelivery.
 **`Consumer`** — `subscribe(workflowId, processJob)` routes deliveries for
 one workflow to a callback; `cleanUp()` releases resources.
 
-**`JsonStore`** — `save(id, document)`, `retrieve(id)`, `delete(id)`,
-`list()`; implementations validate against a `JsonSchema` when one is given.
+**`JsonStore`** — abstract, `Auditor`-backed and actor-audited like
+`JobPersistence`: `create(actor, id, document)`,
+`save(actor, changeDescription, id, document)`, `retrieve(id, actor)`,
+`delete(id, actor)`, `list(actor, pageSize?, page?)` (returns the document
+values, not ids); implementations validate against a `JsonSchema` when one is given.
 
-**`SecretStore`** — `save(name, value)`, `retrieve(name)`, `list()`.
+**`SecretStore`** — abstract, `Auditor`-backed: `create(actor, name, value)`,
+`save(actor, changeDescription, name, value)`, `retrieve(name, actor)`,
+`delete(name, actor)`, `list(actor)`. Secret values never appear in audit details.
 
 **`QueueMessage`** — `{ jobId, workflowId }`; part of the platform's private
 wire protocol (in `api/cloud/`), exported because `Dequeue` returns it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-tsapi",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "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/AgenticAction.ts

@@ -0,0 +1,24 @@
+import {Agent} from "../actors/agents/Agent";
+import {AgentRequest} from "../actors/agents/AgentRequest";
+import {Job} from "../jobs/Job";
+import {Action} from "./Action";
+
+/* An action whose properties are generated by an agent. run builds a request
+   from the job and hands it to the agent's client; the structured result
+   becomes the property map. Subclasses decide how the request is composed. */
+abstract class AgenticAction extends Action {
+
+    protected agent : Agent;
+
+    constructor(name : string, agent : Agent, description : string = "", id? : string) {
+        super(name, agent, description, id);
+        this.agent = agent;
+        this.run = async (job : Job) =>
+            new Map(Object.entries(await this.agent.client.generate(this.requestFor(job))));
+    }
+
+    protected abstract requestFor(job : Job) : AgentRequest;
+
+}
+
+export { AgenticAction }

package/src/api/actors/Actor.ts

@@ -1,4 +1,4 @@
-type ActorType = "HUMAN" | "CODE" | "AGENT";
+type ActorType = "HUMAN" | "CODE" | "AGENT" | "SYSTEM";
 
 interface Actor {
 

package/src/api/actors/SystemActor.ts

@@ -0,0 +1,13 @@
+import {Actor, ActorType} from "./Actor";
+
+class SystemActor implements Actor {
+
+    type : ActorType = "SYSTEM";
+    id = "_SYSTEM";
+    role = "_SYSTEM";
+
+    static actor = new SystemActor();
+
+}
+
+export { SystemActor }

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

@@ -0,0 +1,32 @@
+import {Actor} from "../Actor";
+import {AgentRequest} from "./AgentRequest";
+
+/* An agent is a light actor: identity only, used for auditing and
+   authorization like any other actor. The functional model detail lives in
+   its Client collaborator, keeping the actor itself pure data. */
+class Agent implements Actor {
+
+    readonly type = "AGENT" as const;
+    readonly id : string;
+    readonly role : string;
+    readonly client : Agent.Client;
+
+    constructor(id : string, role : string, client : Agent.Client) {
+        this.id = id;
+        this.role = role;
+        this.client = client;
+    }
+
+}
+
+namespace Agent {
+
+    export abstract class Client {
+
+        abstract generate(request : AgentRequest) : Promise<Record<string, any>>;
+
+    }
+
+}
+
+export { Agent }

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

@@ -0,0 +1,8 @@
+type AgentMessage = {
+
+    role : "system" | "user" | "assistant";
+    content : string;
+
+};
+
+export type { AgentMessage }

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

@@ -0,0 +1,10 @@
+import {AgentMessage} from "./AgentMessage";
+
+type AgentRequest = {
+
+    messages : Array<AgentMessage>;
+    outputSchema : object;
+
+};
+
+export type { AgentRequest }

package/src/api/auditing/Auditor.ts

@@ -1,12 +1,19 @@
 import {Actor} from "../actors/Actor";
 
-type AuditChange = "CREATE" | "UPDATE_PROPERTIES" | "CHANGE_STATE" | "DELETE";
+enum AuditInteraction {
+    CREATE = "CREATE",
+    UPDATE_PROPERTIES = "UPDATE_PROPERTIES",
+    CHANGE_STATE = "CHANGE_STATE",
+    DELETE = "DELETE",
+    READ = "READ",
+    LIST = "LIST",
+}
 
 interface Auditor {
 
-    audit(jobId : string, actor : Actor, change : AuditChange,
-          changeDescription : string, details : any) : Promise<void>;
+    audit(resourceType : string, resourceId : string, actor : Actor, interaction : AuditInteraction[],
+          description : string, details : any) : Promise<void>;
 
 }
 
-export type { AuditChange, Auditor }
+export { AuditInteraction, Auditor }

package/src/api/auditing/NoOpAuditor.ts

@@ -0,0 +1,15 @@
+import {Actor} from "../actors/Actor";
+import {AuditInteraction, Auditor} from "./Auditor";
+
+/* An auditor that records nothing. Used by the persistence instances that sit
+   behind the HTTP API, where the app-facing store on the other side has
+   already audited the interaction. */
+class NoOpAuditor implements Auditor {
+
+    async audit(_resourceType : string, _resourceId : string, _actor : Actor, _interaction : AuditInteraction[],
+                _description : string, _details : any) : Promise<void> {
+    }
+
+}
+
+export { NoOpAuditor }

package/src/api/cloud/AuditRecord.ts

@@ -1,11 +1,12 @@
-import {AuditChange} from "../auditing/Auditor";
+import {AuditInteraction} from "../auditing/Auditor";
 
 type AuditRecord = {
     id? : string,
-    jobId : string,
+    resourceType : string,
+    resourceId : string,
     actorId : string,
     actorType : string,
-    change : AuditChange,
+    interaction : AuditInteraction[],
     description : string,
     details : any,
     at? : string,

package/src/api/documents/JsonStore.ts

@@ -1,9 +1,42 @@
-interface JsonStore {
+import {Actor} from "../actors/Actor";
+import {AuditInteraction, Auditor} from "../auditing/Auditor";
 
-    save(id : string, document : any) : Promise<void>;
-    retrieve(id : string) : Promise<any>;
-    delete(id : string) : Promise<void>;
-    list(pageSize? : number, page? : number) : Promise<Array<any>>;
+/* A schema-validated JSON document store that audits every interaction, keyed
+   by collection and id. Public methods audit then defer to ...Internal. */
+abstract class JsonStore {
+
+    constructor(protected auditor : Auditor, protected collection : string = "documents") {
+    }
+
+    async create(actor : Actor, id : string, document : any) : Promise<void> {
+        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [AuditInteraction.CREATE], "Document created", document);
+        await this.saveInternal(id, document);
+    }
+
+    async save(actor : Actor, changeDescription : string, id : string, document : any) : Promise<void> {
+        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [AuditInteraction.UPDATE_PROPERTIES], changeDescription, document);
+        await this.saveInternal(id, document);
+    }
+
+    async retrieve(id : string, actor : Actor) : Promise<any> {
+        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [AuditInteraction.READ], "", null);
+        return this.retrieveInternal(id);
+    }
+
+    async delete(id : string, actor : Actor) : Promise<void> {
+        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [AuditInteraction.DELETE], "", null);
+        await this.deleteInternal(id);
+    }
+
+    async list(actor : Actor, pageSize? : number, page? : number) : Promise<Array<any>> {
+        await this.auditor.audit("document", `${this.collection}/*`, actor, [AuditInteraction.LIST], "", null);
+        return this.listInternal(pageSize, page);
+    }
+
+    protected abstract saveInternal(id : string, document : any) : Promise<void>;
+    protected abstract retrieveInternal(id : string) : Promise<any>;
+    protected abstract deleteInternal(id : string) : Promise<void>;
+    protected abstract listInternal(pageSize? : number, page? : number) : Promise<Array<any>>;
 
 }
 

package/src/api/jobs/Job.ts

@@ -1,48 +1,26 @@
 import {Transition} from "../transitions/Transition";
-import {JobTransition} from "./JobTransition";
 
 class Job {
 
     readonly id : string;
-    private state: string;
-    properties : Map<string, any>;
+    readonly state: string;
+    readonly properties : Map<string, any>;
     readonly workflowId? : string;
     readonly startedAt : Date;
     readonly startedBy : string;
-    lastUpdated : Date;
-    readonly transitions : Array<JobTransition>;
+    readonly lastUpdated : Date;
 
-    constructor(id : string, properties : Map<string, any> = new Map(), initialState: string, workflowId? : string,
+    constructor(id : string, properties : Map<string, any> = new Map(), state: string, workflowId? : string,
                 startedBy : string = "system", startedAt : Date = new Date(),
-                lastUpdated : Date = startedAt, transitions : Array<JobTransition> = []) {
+                lastUpdated : Date = startedAt) {
+
         this.id = id;
         this.properties = properties;
-        this.state = initialState;
+        this.state = state;
         this.workflowId = workflowId;
         this.startedBy = startedBy;
         this.startedAt = startedAt;
         this.lastUpdated = lastUpdated;
-        this.transitions = transitions;
-    }
-
-    private setState(stateId : string) : void {
-        this.state = stateId;
-    }
-
-    get stateId() : string | undefined {
-        return this.state;
-    }
-
-    transition(transition : Transition, actor : string = this.workflowId ?? "state-machine") : boolean {
-
-        if (transition.predicate(this)) {
-            this.transitions.push({ from: this.state, to: transition.to, actor });
-            this.setState(transition.to);
-            this.lastUpdated = new Date();
-            return true;
-        }
-
-        return false;
     }
 
 }

package/src/api/jobs/JobPersistence.ts

@@ -1,12 +1,90 @@
+import {Actor} from "../actors/Actor";
+import {AuditInteraction, Auditor} from "../auditing/Auditor";
 import {Job} from "./Job";
+import {SystemActor} from "../actors/SystemActor";
 
-interface JobPersistence {
+/* Persists jobs and audits every interaction. Public methods record the
+   interaction against the injected auditor and then defer to the abstract
+   ...Internal methods a concrete store implements. */
+abstract class JobPersistence {
 
-    save(job : Job) : Promise<void>;
-    retrieve(id : string) : Promise<Job>;
-    delete(id : string) : Promise<void>;
-    list(pageSize? : number, page? : number) : Promise<Array<Job>>;
-    updateProperties(id : string, properties : Map<string, any>) : Promise<void>;
+    constructor(protected auditor : Auditor) {
+    }
+
+    async create(actor : Actor,
+               job : Job) : Promise<void> {
+
+        await this.auditor.audit("job", job.id, actor, [AuditInteraction.CREATE], "Job created", job);
+
+        this.saveInternal(job);
+    }
+
+    async save(actor : Actor,
+               changeDescription : string,
+               job : Job,
+               properties? : Map<string, any>,
+               state? : string) : Promise<void> {
+
+        const change = {
+            properties: properties ? this.generatePropertiesDiff(job.properties, properties) : undefined,
+            state: state ? {from : job.state, to : state} : undefined
+        }
+
+        const interaction = [];
+        if (properties) interaction.push(AuditInteraction.UPDATE_PROPERTIES);
+        if (state) interaction.push(AuditInteraction.CHANGE_STATE);
+
+        await this.auditor.audit("job", job.id, actor, interaction, changeDescription, change);
+
+        const updatedJob = new Job(
+            job.id,
+            properties ? this.updateProperties(job.properties, properties) : job.properties,
+            state ? state : job.state,
+            job.workflowId,
+            job.startedBy,
+            job.startedAt,
+            new Date()
+        )
+
+        this.saveInternal(updatedJob);
+    }
+
+    private generatePropertiesDiff(oldVersion : Map<string, any>, newVersion : Map<string, any>) : Map<string, {from: any, to: any}> {
+        const diff: Map<string, { from: any; to: any; }> = new Map();
+
+        for (const [key, value] of newVersion) {
+            diff.set(key, {from: oldVersion.get(key), to: value});
+        }
+        return diff;
+    }
+
+    private updateProperties(oldVersion : Map<string, any>, newVersion : Map<string, any>) : Map<string, any> {
+        const updated = new Map(oldVersion);
+        for (const [key, value] of newVersion) {
+            updated.set(key, value);
+        }
+        return updated;
+    }
+
+    async retrieve(id : string, actor : Actor) : Promise<Job> {
+        await this.auditor.audit("job", id, actor, [AuditInteraction.READ], "", null);
+        return this.retrieveInternal(id);
+    }
+
+    async delete(id : string, actor : Actor) : Promise<void> {
+        await this.auditor.audit("job", id, actor, [AuditInteraction.DELETE], "", null);
+        await this.deleteInternal(id);
+    }
+
+    async list(actor : Actor, pageSize? : number, page? : number) : Promise<Array<Job>> {
+        await this.auditor.audit("job", "*", actor, [AuditInteraction.LIST], "", null);
+        return this.listInternal(pageSize, page);
+    }
+
+    protected abstract saveInternal(job : Job) : Promise<void>;
+    protected abstract retrieveInternal(id : string) : Promise<Job>;
+    protected abstract deleteInternal(id : string) : Promise<void>;
+    protected abstract listInternal(pageSize? : number, page? : number) : Promise<Array<Job>>;
 
 }
 

package/src/api/jobs/JobSerialization.ts

@@ -1,5 +1,4 @@
 import {Job} from "./Job";
-import {JobTransition} from "./JobTransition";
 
 type SerializedJob = {
     id : string,
@@ -9,26 +8,23 @@ type SerializedJob = {
     startedAt? : string,
     startedBy? : string,
     lastUpdated? : string,
-    transitions? : Array<JobTransition>,
 };
 
 const serializeJob = (job : Job) : SerializedJob => ({
     id: job.id,
-    state: job.stateId!,
+    state: job.state,
     properties: Object.fromEntries(job.properties),
     workflowId: job.workflowId,
     startedAt: job.startedAt.toISOString(),
     startedBy: job.startedBy,
     lastUpdated: job.lastUpdated.toISOString(),
-    transitions: job.transitions,
 });
 
 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.transitions ?? []);
+        serialized.lastUpdated ? new Date(serialized.lastUpdated) : startedAt);
 };
 
 export { serializeJob, deserializeJob };

package/src/api/secrets/SecretStore.ts

@@ -1,9 +1,43 @@
-interface SecretStore {
+import {Actor} from "../actors/Actor";
+import {AuditInteraction, Auditor} from "../auditing/Auditor";
 
-    save(name : string, value : string) : Promise<void>;
-    retrieve(name : string) : Promise<string>;
-    delete(name : string) : Promise<void>;
-    list() : Promise<Array<string>>;
+/* Stores named secrets and audits every interaction. The secret value is
+   never included in an audit record. Public methods audit then defer to the
+   abstract ...Internal methods. */
+abstract class SecretStore {
+
+    constructor(protected auditor : Auditor) {
+    }
+
+    async create(actor : Actor, name : string, value : string) : Promise<void> {
+        await this.auditor.audit("secret", name, actor, [AuditInteraction.CREATE], "Secret created", null);
+        await this.saveInternal(name, value);
+    }
+
+    async save(actor : Actor, changeDescription : string, name : string, value : string) : Promise<void> {
+        await this.auditor.audit("secret", name, actor, [AuditInteraction.UPDATE_PROPERTIES], changeDescription, null);
+        await this.saveInternal(name, value);
+    }
+
+    async retrieve(name : string, actor : Actor) : Promise<string> {
+        await this.auditor.audit("secret", name, actor, [AuditInteraction.READ], "", null);
+        return this.retrieveInternal(name);
+    }
+
+    async delete(name : string, actor : Actor) : Promise<void> {
+        await this.auditor.audit("secret", name, actor, [AuditInteraction.DELETE], "", null);
+        await this.deleteInternal(name);
+    }
+
+    async list(actor : Actor) : Promise<Array<string>> {
+        await this.auditor.audit("secret", "*", actor, [AuditInteraction.LIST], "", null);
+        return this.listInternal();
+    }
+
+    protected abstract saveInternal(name : string, value : string) : Promise<void>;
+    protected abstract retrieveInternal(name : string) : Promise<string>;
+    protected abstract deleteInternal(name : string) : Promise<void>;
+    protected abstract listInternal() : Promise<Array<string>>;
 
 }
 

package/src/index.ts

@@ -1,13 +1,18 @@
 export * from "./api/jobs/Job";
 export * from "./api/jobs/JobPersistence"
 export * from "./api/jobs/JobSerialization"
-export * from "./api/jobs/JobTransition"
 export * from "./api/jobs/PropertyDefinition"
 export * from "./api/states/State"
 export * from "./api/actions/Action"
+export * from "./api/actions/AgenticAction"
+export * from "./api/actors/agents/AgentMessage"
+export * from "./api/actors/agents/AgentRequest"
+export * from "./api/actors/agents/Agent"
 export * from "./api/auditing/Auditor"
+export * from "./api/auditing/NoOpAuditor"
 export * from "./api/transitions/Transition"
 export * from "./api/actors/Actor"
+export * from "./api/actors/SystemActor"
 export * from "./api/documents/JsonStore"
 export * from "./api/secrets/SecretStore"
 export * from "./api/documents/JsonSchema"

package/src/api/jobs/JobTransition.ts

@@ -1,7 +0,0 @@
-type JobTransition = {
-    from : string,
-    to : string,
-    actor : string,
-};
-
-export type { JobTransition }