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

package/dist/server/distribution/download-tokens.js

@@ -0,0 +1,82 @@
+/**
+ * Download tokens: what a signed-in person hands to the install script (`HEADERS.downloadToken`) so that a machine
+ * where nobody is signed in yet can download the application's CLI (`agents.cli`, such as `acme`), for instance a coding
+ * agent following the prompt an application's home page copies. A token reaches the CLI's manifest, its current version for one platform and that tarball, for
+ * `DOWNLOAD_TOKEN_TTL_MS` and at most `DOWNLOAD_TOKEN_MAX_DOWNLOADS` downloads; the platform of its first request binds
+ * it. It grants nothing a signed-in person could not download anyway, and registers no runner. Like the other
+ * credentials only its hash is stored (`agDownloadTokens`); only this file reads or writes them.
+ */
+import { ProtocolError } from '@nocobase/agent-protocol';
+import { later } from '../kernel/clock.js';
+import { CREDENTIAL_PREFIX, createCredential, hashCredential, } from '../kernel/crypto.js';
+/** How long a download token stays usable. */
+export const DOWNLOAD_TOKEN_TTL_MS = 30 * 60_000;
+/** How many tarball downloads one token allows, so a failed download can be retried. */
+export const DOWNLOAD_TOKEN_MAX_DOWNLOADS = 3;
+function downloadTokensRepo(conn) {
+    return conn.repository('agDownloadTokens');
+}
+export function createDownloadTokenService(deps) {
+    const { tx, ids, clock, product } = deps;
+    const invalid = (message) => new ProtocolError('DOWNLOAD_TOKEN_INVALID', message);
+    const spent = () => invalid('The download token is unknown, expired or used up. Get a new one where you copied it.');
+    return {
+        create: (createdById) => tx.run(async ({ conn }) => {
+            const now = clock.now();
+            const token = createCredential(CREDENTIAL_PREFIX.download);
+            const expiresAt = later(now, DOWNLOAD_TOKEN_TTL_MS);
+            await downloadTokensRepo(conn).createOne({
+                values: {
+                    id: ids.next(),
+                    tokenHash: hashCredential(token),
+                    createdById,
+                    target: null,
+                    downloads: 0,
+                    expiresAt,
+                    createdAt: now.toISOString(),
+                },
+            });
+            return {
+                token,
+                expiresAt,
+                maxDownloads: DOWNLOAD_TOKEN_MAX_DOWNLOADS,
+            };
+        }),
+        admit: (token, request) => tx.run(async ({ conn }) => {
+            if (request.product !== undefined && request.product !== product)
+                throw invalid(`A download token downloads only ${product}.`);
+            const tokens = downloadTokensRepo(conn);
+            const record = token
+                ? await tokens.findOne({
+                    filter: { tokenHash: hashCredential(token) },
+                })
+                : undefined;
+            const downloads = Number(record?.downloads ?? 0);
+            if (!record ||
+                Date.parse(record.expiresAt) <= clock.now().getTime() ||
+                downloads >= DOWNLOAD_TOKEN_MAX_DOWNLOADS)
+                throw spent();
+            const { target } = request;
+            if (target === undefined)
+                return;
+            if (record.target !== null && record.target !== target)
+                throw invalid(`This download token is for ${record.target}, not ${target}.`);
+            if (record.target === target && !request.download)
+                return;
+            // Binds the platform and counts the download; a concurrent request that changed the row first wins.
+            const updated = await tokens.updateMany({
+                filter: (f) => f.and([
+                    f.string('id').eq(record.id),
+                    f.number('downloads').eq(downloads),
+                ]),
+                values: {
+                    target,
+                    downloads: request.download ? downloads + 1 : downloads,
+                },
+            });
+            if (updated.updatedCount !== 1)
+                throw spent();
+        }),
+    };
+}
+//# sourceMappingURL=download-tokens.js.map

package/dist/server/distribution/download-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download-tokens.js","sourceRoot":"","sources":["../../../server/distribution/download-tokens.ts"],"names":[],"mappings":"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"}

package/dist/server/distribution/index.d.ts

@@ -0,0 +1,14 @@
+import { type UpgradeNotice } from '@nocobase/agent-protocol';
+import type { Runner } from '../../shared/runners.js';
+import type { DistService } from './dist.service.js';
+export { createDownloadTokenService, DOWNLOAD_TOKEN_MAX_DOWNLOADS, DOWNLOAD_TOKEN_TTL_MS, type DownloadRequest, type DownloadTokenService, } from './download-tokens.js';
+export { createDistService, DEFAULT_CHANNEL, type DistConfig, type DistFile, type DistService, } from './dist.service.js';
+/** The platform a runner reported, as the tarballs name it. */
+export declare function runnerTarget(runner: Pick<Runner, 'os' | 'arch'>): string;
+/**
+ * A newer version of the product `runner` runs as (`nocobase-runner`, or a CLI that carries the runner) that the
+ * application serves for its platform, if there is one. A runner that reported no product is offered none: it may be
+ * carried by a CLI that no longer carries it.
+ */
+export declare function upgradeFor(dist: DistService, runner: Pick<Runner, 'os' | 'arch' | 'version' | 'product'>): Promise<UpgradeNotice | undefined>;
+//# sourceMappingURL=index.d.ts.map

package/dist/server/distribution/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../server/distribution/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC5B,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAE3B,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC,GAAG,MAAM,CAExE;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC,GAC1D,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAapC"}

package/dist/server/distribution/index.js

@@ -0,0 +1,28 @@
+import { compareVersions } from '@nocobase/agent-protocol';
+export { createDownloadTokenService, DOWNLOAD_TOKEN_MAX_DOWNLOADS, DOWNLOAD_TOKEN_TTL_MS, } from './download-tokens.js';
+export { createDistService, DEFAULT_CHANNEL, } from './dist.service.js';
+/** The platform a runner reported, as the tarballs name it. */
+export function runnerTarget(runner) {
+    return `${runner.os}-${runner.arch}`;
+}
+/**
+ * A newer version of the product `runner` runs as (`nocobase-runner`, or a CLI that carries the runner) that the
+ * application serves for its platform, if there is one. A runner that reported no product is offered none: it may be
+ * carried by a CLI that no longer carries it.
+ */
+export async function upgradeFor(dist, runner) {
+    if (runner.product === null)
+        return undefined;
+    const latest = await dist.find(runner.product, runnerTarget(runner));
+    if (!latest || compareVersions(latest.version, runner.version) <= 0)
+        return undefined;
+    return {
+        minVersion: '0.0.0',
+        latestVersion: latest.version,
+        downloadUrl: latest.url,
+        sha256: latest.sha256,
+        channel: latest.channel,
+        reason: `The application serves ${latest.product} ${latest.version} on the ${latest.channel} channel.`,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/server/distribution/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../server/distribution/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAsB,MAAM,0BAA0B,CAAC;AAI/E,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC5B,qBAAqB,GAGtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EACjB,eAAe,GAIhB,MAAM,mBAAmB,CAAC;AAE3B,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAAC,MAAmC;IAC9D,OAAO,GAAG,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAiB,EACjB,MAA2D;IAE3D,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC9C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IACrE,IAAI,CAAC,MAAM,IAAI,eAAe,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QACjE,OAAO,SAAS,CAAC;IACnB,OAAO;QACL,UAAU,EAAE,OAAO;QACnB,aAAa,EAAE,MAAM,CAAC,OAAO;QAC7B,WAAW,EAAE,MAAM,CAAC,GAAG;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,0BAA0B,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,WAAW,MAAM,CAAC,OAAO,WAAW;KACvG,CAAC;AACJ,CAAC"}

package/dist/server/index.d.ts

@@ -0,0 +1,4 @@
+export { default } from './plugin.js';
+/** What the plugin registers with the authorization plugin at boot, for an application or a test assembling it by hand. */
+export { registerBusinesses, registerSettings, } from './providers/authorization.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,2HAA2H;AAC3H,OAAO,EACL,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,8BAA8B,CAAC"}

package/dist/server/index.js

@@ -0,0 +1,4 @@
+export { default } from './plugin.js';
+/** What the plugin registers with the authorization plugin at boot, for an application or a test assembling it by hand. */
+export { registerBusinesses, registerSettings, } from './providers/authorization.js';
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,2HAA2H;AAC3H,OAAO,EACL,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,8BAA8B,CAAC"}

package/dist/server/jobs/index.d.ts

@@ -0,0 +1,5 @@
+export { createJobService, jobFits, type EnqueueJobInput, type JobChange, type JobRunnerReports, type JobSecretSource, type JobService, type JobServiceDeps, type JobSweepReport, } from './job.service.js';
+export { activeJobsOn } from './job.store.js';
+export { createJobKindRegistry, type JobKindRegistration, type JobKindRegistry, type JobPrepareContext, type RegisteredJobKind, } from './registry.js';
+export { checkSpecInput, JobSecretsNotAllowed, runnerSpec, secretRefsOf, type BuildJobSpecInput, type JobEnvInput, type JobRepoInput, type JobSpecInput, type JobSpecInputs, type SecretRef, } from './spec.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/jobs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../server/jobs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,OAAO,EACP,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,SAAS,GACf,MAAM,WAAW,CAAC"}

package/dist/server/jobs/index.js

@@ -0,0 +1,5 @@
+export { createJobService, jobFits, } from './job.service.js';
+export { activeJobsOn } from './job.store.js';
+export { createJobKindRegistry, } from './registry.js';
+export { checkSpecInput, JobSecretsNotAllowed, runnerSpec, secretRefsOf, } from './spec.js';
+//# sourceMappingURL=index.js.map

package/dist/server/jobs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../server/jobs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,OAAO,GAQR,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,qBAAqB,GAKtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,YAAY,GAOb,MAAM,WAAW,CAAC"}

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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"}