@nocobase/app-plugin-agents 0.0.0-stage → 0.1.0-beta.10

package/dist/server/jobs/job.service.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Jobs: deterministic steps a runner executes without a model, for the application that registers their kinds. A job
+ * is not a run: it has no agent, brief or run token, never wakes an agent, and is not counted in an agent's runs or
+ * reports. It shares a run's mechanics, re-implemented on its own collection so that nothing about runs changes:
+ *
+ * - the queue: priority, then age; a failed attempt with a retryable reason goes back to the queue while attempts
+ *   remain;
+ * - the claim: the same long-poll hands out runs and jobs, from the same runner slots. A runner fits a job when its
+ *   owner let it take jobs (`acceptJobs`), it reports the executor's feature (`jobs.build`), it is shared with the team
+ *   or belongs to the person who started the job, the job names no runner or names it, and its owner's local policy
+ *   lets it check out the job's repository. The claim is one transaction: a guarded update takes the job, the kind's
+ *   `prepare` gives the spec, stored variables it names are opened for this runner through the application's secret
+ *   source (`secrets`), and the payload is assembled; a failure rolls back and is counted;
+ * - the lease, events, the ending reports and the heartbeat's reconciliation, as for runs;
+ * - the sweeper (`sweep`, called by the runners sweeper): takes jobs back from runners that went silent, lost their lease
+ *   or never started, fails a job running well past its `timeoutSec`, and records unacknowledged cancellations.
+ */
+import { type ActiveJob, type EventsResponse, type JobCompleteRequest, type JobEventsRequest, type JobFailRequest, type JobFinishResponse, type JobLeaseResponse, type JobPayload, type JobStartRequest, type JobStatus, type JobStatusResponse, type RunApp } from '@nocobase/agent-protocol';
+import type { DatabaseConnection } from '@nocobase/db';
+import type { Job, JobEventView, JobFilter, JobVia } from '../../shared/jobs.js';
+import { type Runner } from '../../shared/runners.js';
+import { type Clock } from '../kernel/clock.js';
+import type { AgentsEventBus } from '../kernel/events.js';
+import type { IdSource } from '../kernel/ids.js';
+import { type SecretMemory } from '../kernel/redaction.js';
+import type { Tx, TxRunner } from '../kernel/tx.js';
+import { type JobRecord } from './job.store.js';
+import type { JobKindRegistration, JobKindRegistry, RegisteredJobKind } from './registry.js';
+import { type SecretRef } from './spec.js';
+export interface EnqueueJobInput {
+    /** A kind the application registered (`jobs.register`). */
+    readonly kind: string;
+    /** What `validate` checks; without one, the executor's spec with references to stored variables (`JobSpecInputs`). */
+    readonly spec: unknown;
+    /** The person on whose behalf it runs: a personal runner takes only its owner's jobs. */
+    readonly actorUserId: string;
+    /** `human` by default. An agent's request is recorded as `agent`, with the person who woke it as the actor. */
+    readonly via?: JobVia;
+    /** What it is for, as the application names it; for finding its jobs again. */
+    readonly subject?: {
+        readonly kind: string;
+        readonly id: string;
+    };
+    readonly title?: string;
+    /** Only these runners may take it. */
+    readonly runnerIds?: readonly string[];
+    /** Lower runs first; 0 by default. */
+    readonly priority?: number;
+    /** 2 by default, at most 5. */
+    readonly maxAttempts?: number;
+}
+/** What `watch` hears, after the change commits. */
+export type JobChange = {
+    readonly type: 'status';
+    readonly jobId: string;
+    readonly status: JobStatus;
+} | {
+    readonly type: 'events';
+    readonly jobId: string;
+    readonly lastSeq: number;
+};
+export interface JobSweepReport {
+    readonly requeued: number;
+    readonly failed: number;
+    readonly cancelled: number;
+}
+/** The runner protocol's side of jobs, for the runner routes. */
+export interface JobRunnerReports {
+    /** Up to `free` jobs for `runner` (within its slots, shared with runs), each with its payload. */
+    claim(runner: Runner, free: number): Promise<JobPayload[]>;
+    lease(runner: Runner, jobId: string): Promise<JobLeaseResponse>;
+    start(runner: Runner, jobId: string, request: JobStartRequest): Promise<JobLeaseResponse>;
+    events(runner: Runner, jobId: string, request: JobEventsRequest): Promise<EventsResponse>;
+    status(runner: Runner, jobId: string): Promise<JobStatusResponse>;
+    complete(runner: Runner, jobId: string, request: JobCompleteRequest): Promise<JobFinishResponse>;
+    fail(runner: Runner, jobId: string, request: JobFailRequest): Promise<JobFinishResponse>;
+    cancelAck(runner: Runner, jobId: string): Promise<JobFinishResponse>;
+    /** Compares the jobs a heartbeat says the runner holds with what the server thinks. */
+    reconcile(runner: Runner, active: readonly ActiveJob[]): Promise<{
+        cancelRequested: string[];
+        release: string[];
+    }>;
+}
+/**
+ * Where the stored variables a job names are opened, as the application provides it (the agents plugin's variables).
+ * Each value is keyed `scope\u0000scopeId\u0000name`; a name it does not hold is left out. It records the delivery.
+ * Throw `JobSecretsNotAllowed` when a personal runner asks for a team-only variable: the claim rolls back and the job
+ * stays queued without counting a preparation failure.
+ */
+export interface JobSecretSource {
+    open(conn: DatabaseConnection, refs: readonly SecretRef[], delivery: {
+        readonly jobId: string;
+        readonly runnerId: string;
+    }): Promise<Map<string, string>>;
+}
+/** The application's API for jobs (`runners.jobs`). */
+export interface JobService {
+    /** Registers a kind of job the application enqueues; at boot. */
+    register<Spec>(kind: string, registration: JobKindRegistration<Spec>): void;
+    /** The registered kinds. */
+    kinds(): readonly RegisteredJobKind[];
+    /** Queues a job; with `tx`, inside that unit of work (announced when it commits). */
+    enqueue(input: EnqueueJobInput, tx?: Tx): Promise<Job>;
+    /**
+     * Cancels a job: a queued one at once, a held one once its runner stops it (or the sweeper gives up waiting). An
+     * ended job is answered as it is.
+     */
+    cancel(jobId: string, byUserId: string | null, tx?: Tx): Promise<Job>;
+    /** 404 when absent. */
+    get(jobId: string): Promise<Job>;
+    find(conn: DatabaseConnection, jobId: string): Promise<Job | null>;
+    /** Newest first. `actorUserId` and `visibleTo` narrow it to a person's own jobs. */
+    list(filter?: JobFilter & {
+        readonly actorUserId?: string;
+        /** Jobs this person started or that ran on one of these runners. */
+        readonly visibleTo?: {
+            readonly userId: string;
+            readonly runnerIds: readonly string[];
+        };
+    }): Promise<Job[]>;
+    /** The job's log after `afterSeq`, oldest first. */
+    events(jobId: string, afterSeq?: number, limit?: number): Promise<JobEventView[]>;
+    /** Hears every job's changes, or one job's; returns what stops listening. */
+    watch(jobId: string | null, listener: (change: JobChange) => void): () => void;
+    /** For the runner routes. */
+    readonly runner: JobRunnerReports;
+    /** For the sweeper. */
+    sweep(): Promise<JobSweepReport>;
+    /**
+     * Sets where the secrets jobs name are opened; returns what removes it. Without one, a job naming a secret cannot be
+     * claimed and fails `setupFailed` after a few claims.
+     */
+    provideSecrets(source: JobSecretSource): () => void;
+}
+export interface JobServiceDeps {
+    readonly tx: TxRunner;
+    readonly ids: IdSource;
+    readonly clock: Clock;
+    readonly events: AgentsEventBus;
+    readonly kinds: JobKindRegistry;
+    readonly app: RunApp;
+    /** Items each runner holds now, jobs and the registered work kinds' together: its slots are shared. */
+    readonly slotsUsed: (conn: DatabaseConnection, runnerId: string) => Promise<number>;
+    /**
+     * The secrets claims handed out. Job events and failure details are redacted of them and of the common patterns
+     * before they are stored, whatever the runner did (`kernel/redaction.ts`).
+     */
+    readonly secrets?: SecretMemory;
+    readonly onError?: (message: string, error: unknown) => void;
+}
+/** Whether `runner` may take `job`, before any lock is taken. */
+export declare function jobFits(runner: Runner, job: JobRecord): boolean;
+export declare function createJobService(deps: JobServiceDeps): JobService;
+//# sourceMappingURL=job.service.d.ts.map

package/dist/server/jobs/job.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.service.d.ts","sourceRoot":"","sources":["../../../server/jobs/job.service.ts"],"names":[],"mappings":"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"}