aec-agent 1.0.3 → 1.0.4

package/dist/components/multi-agent-orchestration/agent/job-manager/job-manager.d.ts

@@ -0,0 +1,208 @@
+import type { Message, ToolCall, ToolResult } from "../../../../kernel/types.js";
+import type { EventBus } from "../../../event-handler/types.js";
+import type { SessionStore } from "../../../persistence-hub/types/session-store.js";
+import type { JobStore } from "../../../persistence-hub/types/job-store.js";
+import type { InteractionHandler } from "../../../tool-hub/types.js";
+import { type AgentJobs, type CreateJobInput, type Job, type JobAcceptResult, type JobEvent, type JobRun, type JobRunner, type JobTestEventInput, type JobWebhookRequest, type JobWebhookResponse, type UpdateJobInput } from "./types.js";
+/** How long a claimed run is leased; renewed every third of it while the turn runs. */
+export declare const JOB_LEASE_MS = 60000;
+/** How often the worker looks for due runs it was not told about (other processes, expired leases). */
+export declare const JOB_POLL_MS = 10000;
+/** First retry delay; doubles per attempt, with ±25% jitter, at most 15 minutes. */
+export declare const JOB_RETRY_BASE_MS = 30000;
+/** Job runs of one agent at once in this process. */
+export declare const MAX_PARALLEL_JOB_RUNS = 4;
+/** History kept per job. */
+export declare const KEEP_JOB_EVENTS = 200;
+export declare const KEEP_JOB_RUNS = 100;
+export interface JobManagerDeps {
+    agentId: string;
+    eventBus: EventBus;
+    /** Resolved on every call so a later persistence swap (AgentCore.usePersistence) is picked up. */
+    getStore: () => JobStore;
+    getSessions: () => SessionStore;
+    /** Resolved on every run — the host's runner, or the agent's default one. */
+    getRunner: () => JobRunner;
+    /** The agent's running turns and its cap (0 = none): job runs leave room for chats. */
+    getCapacity: () => {
+        running: number;
+        max: number;
+    };
+    /**
+     * A-103: runs one tool call outside a turn, the way a turn's call runs (tool policy,
+     * approval gate, retries, tracing) — the agent loop. Absent = the agent can't run tool jobs.
+     */
+    runTool?: (call: ToolCall, options: {
+        sessionId: string;
+        signal: AbortSignal;
+    }) => Promise<ToolResult & {
+        empty?: boolean;
+    }>;
+    /** A-103: why `name` can't be a tool job's tool for this agent (not one of its tools, not schedulable); undefined = it can. */
+    checkTool?: (name: string) => string | undefined;
+    /** A-103: adds a message to a session — a tool job's call and its result. */
+    appendMessage?: (sessionId: string, message: Message) => Promise<void>;
+    /** Clock — injectable for tests. */
+    now?: () => number;
+    /** Jitter source — injectable for tests. */
+    random?: () => number;
+    pollMs?: number;
+    leaseMs?: number;
+    retryBaseMs?: number;
+    maxParallelRuns?: number;
+}
+/**
+ * One agent's event triggers (A-70): takes events into the durable inbox and
+ * runs them as agent turns.
+ *
+ *  - Intake: the agent's own SDK events (pub-sub, never a direct call from the
+ *    scheduler or channels), signed webhooks (handleWebhook) and test events go
+ *    through one path: filter → loop guard → TriggerStore.accept() (dedupe +
+ *    coalesce into a run, atomically).
+ *  - Worker: claims due runs with a lease (TriggerStore.claim), so a run is
+ *    worked by one worker at a time and a run whose worker died is taken over
+ *    when its lease expires. Before a turn it re-checks the trigger (deleted,
+ *    disabled, changed), stale revisions, a resolved condition and the rate and
+ *    token limits. The turn goes through the host's TriggerRunner in a fresh
+ *    session; per-session ordering and the agent's turn cap apply as for any turn,
+ *    and runs leave a turn free for people's chats.
+ *  - Results: the reply is checkpointed before the run is marked finished, so a
+ *    crash in between only re-records the result, it does not re-run the turn.
+ *    Transient failures retry with backoff within maxAttempts and the run's
+ *    deadline. Approvals cannot be given in an unattended run: the tool is denied
+ *    and the run ends "blocked".
+ *
+ * Update (A-126): the JobManager — one agent's jobs of every kind. Schedule jobs'
+ * ticks (the JobClock), run now, bus events, webhooks and test events all go through
+ * the intake above, and one worker runs them. A run's session follows the job's
+ * sessionMode (fresh, or one reused session). A run's reply may carry a marker:
+ * [[SILENT]] (nothing to report: succeeded, never delivered) or [[FAILED]] <reason>
+ * (failed, not retried).
+ */
+export declare class JobManager implements AgentJobs {
+    private deps;
+    /** This worker's lease identity. */
+    private readonly owner;
+    private active;
+    /** sessionId -> the run working in it. */
+    private bySession;
+    /** Intakes and runs in flight — dispose() waits for them. */
+    private inFlight;
+    /**
+     * Schedule jobs whose overlap check and queueing are in progress: a second tick or
+     * run now meanwhile sees the job as busy, so two fired at the same moment cannot
+     * both pass the check (the slot is taken before any await).
+     */
+    private queuing;
+    private unsubscribe;
+    private readonly clock;
+    private pollTimer?;
+    private wakeTimer?;
+    private pumping;
+    private pumpAgain;
+    private started;
+    private disposed;
+    private readonly now;
+    private readonly random;
+    private readonly leaseMs;
+    constructor(deps: JobManagerDeps);
+    /**
+     * The InteractionHandler for a session while a job run works in it: nobody
+     * is there to answer, so approvals are denied (the run ends "blocked") and
+     * questions fail. Undefined for any other session.
+     */
+    interactionFor(sessionId: string): InteractionHandler | undefined;
+    /**
+     * Start the agent's jobs: arm schedule jobs (a time missed while the host was down
+     * runs once), and work the queue — due runs, runs left by a previous process (their
+     * leases expire) and retries. Call once the host is ready to run turns. Idempotent.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the clock, intake and the worker. Runs in progress are aborted and released,
+     * so they are taken up again (not lost, not counted as an attempt) after a restart.
+     */
+    dispose(): Promise<void>;
+    list(): Promise<Job[]>;
+    get(id: string): Promise<Job | null>;
+    create(input: CreateJobInput): Promise<Job>;
+    update(id: string, patch: UpdateJobInput): Promise<Job>;
+    delete(id: string): Promise<void>;
+    rotateSecret(id: string): Promise<Job>;
+    runNow(id: string): Promise<JobRun>;
+    sendTestEvent(id: string, input: JobTestEventInput): Promise<JobAcceptResult>;
+    handleWebhook(id: string, request: JobWebhookRequest): Promise<JobWebhookResponse>;
+    listEvents(id: string, limit?: number): Promise<JobEvent[]>;
+    listRuns(id: string, limit?: number): Promise<JobRun[]>;
+    getRun(runId: string): Promise<JobRun | null>;
+    getRunEvents(runId: string): Promise<JobEvent[]>;
+    stopRun(runId: string): Promise<boolean>;
+    replayRun(runId: string): Promise<JobRun>;
+    /** Whether a run of this job is queued or running. */
+    isRunning(id: string): Promise<boolean>;
+    /** A-103: a tool job's tool must be one of the agent's tools and marked schedulable. */
+    private checkToolAction;
+    /** A schedule job's time came (the JobClock): one tick into its inbox. */
+    private onTick;
+    /** One of the agent's SDK events: offer it to every enabled "event" job. */
+    private onBusEvent;
+    /**
+     * The single intake path: build the inbox entry, filter it, apply the loop
+     * guard, and accept it into the store (dedupe + coalesce, atomically).
+     * `suppress` records the event as suppressed for that reason (a busy schedule job).
+     */
+    private ingest;
+    /** When `sessionId` is a job run's session, the run and chain depth an event from it continues. */
+    private originOf;
+    /** Arm a wake-up for a run that becomes due at `at` (only the soonest is kept). */
+    private wakeAt;
+    /** Claim and start due runs while there is room. Re-entrant calls coalesce. */
+    private pump;
+    private claimLoop;
+    /** Room for one more run: under this manager's cap, and a turn left for people's chats. */
+    private hasRoom;
+    private launch;
+    /** Work one claimed run to its next state. */
+    private process;
+    /**
+     * Record the checkpointed result as the run's outcome; the in-app delivery is this same write.
+     * Update (A-126): the reply's marker decides it — [[SILENT]] succeeds without anything to
+     * deliver, [[FAILED]] <reason> fails (a deliberate answer, so it is not retried).
+     */
+    private finalize;
+    private finish;
+    private emitFinished;
+    /** A lease-guarded write. Null (and the entry marked) when this worker no longer holds the run. */
+    private write;
+    /** Record a job's run state; a failure is logged — the run's own record is what counts. */
+    private setJobState;
+    /**
+     * The session a run writes into — created on the first attempt and reused by retries.
+     * A "reuse" job appends every run to one session, created on its first run.
+     */
+    private resolveSession;
+    /**
+     * A-103: one attempt of a tool job. The stored call runs through the agent loop like a
+     * turn's call (policy, approval gate, retries, traces); its approval handler approves
+     * exactly this call. The call and its result go into the run's session, so the session
+     * shows what ran and a follow-up turn sees the output. A follow-up turn ("always", or
+     * "on-failure" when the tool failed) then runs through the host's runner as usual.
+     */
+    private runToolAction;
+    /**
+     * A-103: the number of finished runs in a row that failed or were blocked, when it has
+     * reached the job's pauseAfterFailures (undefined otherwise, or when the job is already
+     * off). Succeeded runs end the streak; suppressed and stopped runs are skipped. Runs from
+     * before the job's last edit don't count, so turning it back on starts a fresh streak.
+     */
+    private failureStreak;
+    /** A-103: the job's earlier runs, for the "since last run" placeholders. */
+    private runHistory;
+    private retryDelay;
+    private track;
+    private require;
+    private requireRun;
+    private store;
+    private iso;
+}
+//# sourceMappingURL=job-manager.d.ts.map

package/dist/components/multi-agent-orchestration/agent/job-manager/job-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-manager.d.ts","sourceRoot":"","sources":["../../../../../src/components/multi-agent-orchestration/agent/job-manager/job-manager.ts"],"names":[],"mappings":"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"}