@gaia-ai/addon-remote-drupal 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @gaia-ai/addon-remote-drupal
+
+GAIA conductor remote addon: the Drupal/JSON:API control-plane remote.
+
+Part of the GAIA CLI. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all addons. Source: https://git.key-tec.de/keytec/gaia (gaia-cli/).

package/dist/src/index.d.ts

@@ -0,0 +1,40 @@
+import type { ActiveRun, ClaimedRun, ClaimOptions, ConductorRegistration, ConductorStatus, FinalizableRun, GaiaRemote, RemotePlugin, RunMetrics, RunWriteAttributes, Ticket, UncleanTicket } from '@gaia-ai/conductor/contract';
+import type { JsonApiClient } from 'dropsh/plugin';
+export declare class DrupalGaiaRemote implements GaiaRemote {
+    private readonly api;
+    constructor(api: JsonApiClient);
+    fetchActiveRuns(id: string): Promise<ActiveRun[]>;
+    activeRunCount(id: string): Promise<number>;
+    claimNext(c: ClaimOptions): Promise<ClaimedRun | null>;
+    getTicket(uuid: string): Promise<Ticket>;
+    getRunWorktree(uuid: string): Promise<string>;
+    getRunTicketIdentifier(uuid: string): Promise<string>;
+    getRunTicketBranchName(uuid: string): Promise<string>;
+    registerConductor(reg: ConductorRegistration): Promise<string>;
+    heartbeat(reg: ConductorRegistration, load: number, lease?: number): Promise<string>;
+    getConductorStatus(id: string): Promise<string | null>;
+    setConductorStatus(id: string, status: string): Promise<void>;
+    listConductors(owner?: 'me'): Promise<ConductorStatus[]>;
+    markRunning(uuid: string, attrs?: RunWriteAttributes): Promise<void>;
+    markFailed(uuid: string, errorLog: string): Promise<void>;
+    fetchFinalizableRuns(id: string): Promise<FinalizableRun[]>;
+    finalizeRun(uuid: string, log: string, metrics?: RunMetrics): Promise<void>;
+    fetchUncleanedTickets(id: string): Promise<UncleanTicket[]>;
+    closeTicket(uuid: string): Promise<void>;
+    markTicketCleanedUp(uuid: string): Promise<void>;
+    /**
+     * Absolute worktree path of the ticket's latest run (highest run id with a
+     * non-empty worktree_path), or '' when none — the cwd the cleanup command
+     * runs in. The conductor persists worktree_path on markRunning, so a done
+     * ticket's run carries the path even after the run closed.
+     */
+    private latestRunWorktree;
+    resolveTicketByIdentifier(project: string, identifier: string): Promise<{
+        uuid: string;
+        title: string;
+    } | null>;
+    private readonly projectUuidCache;
+    private projectUuid;
+}
+export declare function drupalRemote(): RemotePlugin;
+export default drupalRemote;

package/dist/src/index.js

@@ -0,0 +1,399 @@
+// GAIA-224 (Finding 6, decision 8): the Drupal control-plane remote — formerly
+// `@gaia-ai/core`'s `plugins/remote/drupal.ts`, now its own conductor-surface
+// addon. Core ships no plugin implementations; every mountable lives under
+// `addons/*`. The surface contract comes from `@gaia-ai/conductor/contract`
+// (runtime-light: types + the tiny selectors, no engine).
+import { resolveAuth } from 'dropsh';
+import { createHttpClient, createJsonApiClient } from 'dropsh/plugin';
+const ACTIVE = ['claimed', 'running'];
+export class DrupalGaiaRemote {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    async fetchActiveRuns(id) {
+        // The conductor identity `id` is the machine_id (hash of hostname+path).
+        // gaia_run links to its owning conductor via the `conductor_id` entity-ref;
+        // filter on the related conductor's `machine_id` (nested relationship filter).
+        const rows = await this.api
+            .collection('gaia_run')
+            .where('conductor_id.machine_id', '=', id)
+            .whereIn('state', ACTIVE)
+            .fields(['state', 'state_at_start', 'worktree_path'])
+            .page(100)
+            .list();
+        return Promise.all(rows.map(async (r) => ({
+            runUuid: r.id,
+            ticketUuid: r.rel('ticket_id') ?? '',
+            ticketIdentifier: await this.getRunTicketIdentifier(r.id),
+            branchName: await this.getRunTicketBranchName(r.id),
+            state: r.attr('state') ?? '',
+            stateAtStart: r.attr('state_at_start') ?? '',
+            worktreePath: r.attr('worktree_path') ?? '',
+        })));
+    }
+    async activeRunCount(id) {
+        // Filter on the related conductor's `machine_id` (nested relationship filter).
+        return this.api
+            .collection('gaia_run')
+            .where('conductor_id.machine_id', '=', id)
+            .whereIn('state', ACTIVE)
+            .fields(['drupal_internal__id'])
+            .page(100)
+            .count();
+    }
+    async claimNext(c) {
+        const res = (await this.api.post('gaia/claim-next', {
+            data: {
+                attributes: {
+                    lease_seconds: c.leaseSeconds,
+                    // Server (`ConductorResolverTrait`) narrows to the caller's conductor
+                    // by the `machine_id` attribute; `c.conductorId` IS the machine_id.
+                    machine_id: c.conductorId,
+                },
+            },
+        }));
+        if (!res?.data) {
+            return null;
+        }
+        const d = res.data;
+        const rawId = d.attributes?.drupal_internal__id;
+        if (rawId === undefined || rawId === null) {
+            throw new Error(`claimNext: missing drupal_internal__id on run ${d.id}`);
+        }
+        return {
+            runUuid: d.id,
+            runId: Number(rawId),
+            ticketUuid: d.relationships?.ticket_id?.data?.id ?? '',
+            stateAtStart: String(d.attributes?.state_at_start ?? ''),
+            // handler_id was dropped; the handler is the work the run does, i.e. the
+            // ticket state the run started in.
+            handler: String(d.attributes?.state_at_start ?? ''),
+        };
+    }
+    async getTicket(uuid) {
+        // The agent self-reads the ticket + its comments at run start (GAIA-112),
+        // so getTicket needs no ?include=comments — but it DOES sideload labels +
+        // environments (GAIA-144) so a config-side priority(ticket) can read them
+        // without fetching (AC-5).
+        const doc = (await this.api.get(`gaia_ticket/gaia_ticket/${uuid}?include=labels,environments`));
+        const attrs = doc.data?.attributes ?? {};
+        const issueUrl = typeof attrs.origin === 'string' ? attrs.origin : undefined;
+        const included = Array.isArray(doc.included) ? doc.included : [];
+        const byId = new Map(included.map((r) => [`${r.type}:${r.id}`, r]));
+        const refs = (name) => {
+            const data = doc.data?.relationships?.[name]?.data;
+            return Array.isArray(data) ? data : [];
+        };
+        const labels = refs('labels')
+            .map((ref) => byId.get(`${ref.type}:${ref.id}`)?.attributes?.name)
+            .filter((n) => typeof n === 'string');
+        const environments = refs('environments')
+            .map((ref) => {
+            const a = byId.get(`${ref.type}:${ref.id}`)?.attributes ?? {};
+            return {
+                name: typeof a.name === 'string' ? a.name : '',
+                tier: typeof a.tier === 'string' ? a.tier : '',
+            };
+        })
+            .filter((e) => e.name !== '');
+        return {
+            uuid: doc.data?.id ?? uuid,
+            identifier: typeof attrs.identifier === 'string' ? attrs.identifier : uuid,
+            title: typeof attrs.title === 'string' ? attrs.title : '',
+            state: typeof attrs.state === 'string' ? attrs.state : '',
+            branchName: typeof attrs.branch_name === 'string' ? attrs.branch_name : '',
+            ...(typeof attrs.base_branch === 'string' && attrs.base_branch !== ''
+                ? { baseBranch: attrs.base_branch }
+                : {}),
+            ...(typeof attrs.effective_env_vars === 'string' &&
+                attrs.effective_env_vars !== ''
+                ? { effectiveEnvVars: attrs.effective_env_vars }
+                : {}),
+            ...(issueUrl ? { issueUrl } : {}),
+            labels,
+            environments,
+        };
+    }
+    async getRunWorktree(uuid) {
+        const r = await this.api.resource('gaia_run', uuid);
+        return r.attr('worktree_path') ?? '';
+    }
+    async getRunTicketIdentifier(uuid) {
+        const run = await this.api.resource('gaia_run', uuid);
+        const ticketUuid = run.rel('ticket_id');
+        if (!ticketUuid) {
+            return '';
+        }
+        const ticket = await this.api.resource('gaia_ticket', ticketUuid);
+        return ticket.attr('identifier') ?? '';
+    }
+    async getRunTicketBranchName(uuid) {
+        const run = await this.api.resource('gaia_run', uuid);
+        const ticketUuid = run.rel('ticket_id');
+        if (!ticketUuid) {
+            return '';
+        }
+        const ticket = await this.api.resource('gaia_ticket', ticketUuid);
+        return ticket.attr('branch_name') ?? '';
+    }
+    async registerConductor(reg) {
+        const r = await this.api.upsert('gaia_conductor', { path: 'machine_id', value: reg.id }, {
+            attributes: {
+                machine_id: reg.id,
+                status: 'online',
+                workspace_root: reg.workspace,
+                label: reg.label,
+                states: reg.states,
+                max_parallel: reg.max_parallel,
+            },
+            relationships: {
+                owner_user_id: {
+                    data: { type: 'user--user', id: await this.api.me() },
+                },
+                project_id: {
+                    data: {
+                        type: 'gaia_project--gaia_project',
+                        id: await this.projectUuid(reg.project),
+                    },
+                },
+            },
+        });
+        return r.id; // drupal uuid
+    }
+    async heartbeat(reg, load, lease = 300) {
+        // Server-side upsert by machine_id (see HeartbeatResource): never 404s,
+        // heals a vanished registration, and returns the resulting status. Sending
+        // the full registration lets the server recreate the entity when missing.
+        const res = (await this.api.post('gaia/heartbeat', {
+            data: {
+                attributes: {
+                    machine_id: reg.id,
+                    project: reg.project,
+                    states: reg.states,
+                    workspace_root: reg.workspace,
+                    label: reg.label,
+                    max_parallel: reg.max_parallel,
+                    current_load: load,
+                    lease_seconds: lease,
+                },
+            },
+        }));
+        const status = res?.data?.attributes?.status;
+        return typeof status === 'string' ? status : 'online';
+    }
+    async getConductorStatus(id) {
+        const c = await this.api
+            .collection('gaia_conductor')
+            .where('machine_id', '=', id)
+            .fields(['status'])
+            .first();
+        return c ? (c.attr('status') ?? null) : null;
+    }
+    async setConductorStatus(id, status) {
+        const c = await this.api
+            .collection('gaia_conductor')
+            .where('machine_id', '=', id)
+            .first();
+        if (c) {
+            await this.api.update('gaia_conductor', c.id, { attributes: { status } });
+        }
+    }
+    async listConductors(owner) {
+        let col = this.api.collection('gaia_conductor');
+        if (owner === 'me') {
+            col = col.where('owner_user_id.id', '=', await this.api.me());
+        }
+        const rows = await col.page(200).list();
+        return rows.map((r) => ({
+            id: r.attr('machine_id') ?? r.id,
+            project: '',
+            label: r.attr('label') ?? '',
+            status: r.attr('status') ?? '',
+            lastSeen: r.attr('last_seen') ?? 0,
+            load: r.attr('current_load') ?? 0,
+        }));
+    }
+    async markRunning(uuid, attrs) {
+        const t = Math.floor(Date.now() / 1000);
+        await this.api.update('gaia_run', uuid, {
+            attributes: {
+                state: 'running',
+                heartbeat: t,
+                ...(attrs?.worktree_path ? { worktree_path: attrs.worktree_path } : {}),
+                ...(attrs?.agent ? { agent: attrs.agent } : {}),
+            },
+        });
+    }
+    async markFailed(uuid, errorLog) {
+        const t = Math.floor(Date.now() / 1000);
+        await this.api.update('gaia_run', uuid, {
+            attributes: {
+                state: 'failed',
+                error_log: errorLog,
+                closed: true,
+                closed_date: t,
+            },
+        });
+    }
+    async fetchFinalizableRuns(id) {
+        const rows = await this.api
+            .collection('gaia_run')
+            .where('conductor_id.machine_id', '=', id)
+            .where('state', '=', 'done')
+            .where('closed', '=', '0')
+            .fields(['worktree_path', 'agent', 'drupal_internal__id'])
+            .page(100)
+            .list();
+        // No `started_at` read: the run's duration_s is derived from the agent
+        // transcript at finalize (GAIA-151), so the conductor no longer round-trips
+        // the timestamp back through JSON:API.
+        return rows.map((r) => ({
+            runUuid: r.id,
+            // The `#<runId>` tab-label token: scopes the run's tab-close (GAIA-183).
+            runId: Number(r.attr('drupal_internal__id')),
+            worktreePath: r.attr('worktree_path') ?? '',
+            agent: r.attr('agent') ?? '',
+        }));
+    }
+    async finalizeRun(uuid, log, metrics) {
+        const t = Math.floor(Date.now() / 1000);
+        await this.api.update('gaia_run', uuid, {
+            attributes: {
+                closed: true,
+                closed_date: t,
+                ...(log ? { log } : {}),
+                ...(metrics ?? {}),
+            },
+        }); // NO state — the run is already done.
+    }
+    async fetchUncleanedTickets(id) {
+        // Finished tickets whose worktree is not yet torn down (cleaned_up=0),
+        // driven by the durable `cleaned_up` flag (GAIA-89) AND scoped to this
+        // conductor (GAIA-121): only tickets assigned to `id` are loaded, so a
+        // ticket owned by another conductor never reaches the reaper loop. "Finished"
+        // = reached `done` OR already `closed`; the collection builder has no OR, so
+        // this is two AND-queries merged + de-duped by uuid. The `conductor_id`
+        // relationship carries the assigned conductor's `machine_id` — the same
+        // nested filter the sibling reaper queries (`fetchFinalizableRuns` etc.) use.
+        const fields = ['branch_name', 'state', 'closed'];
+        const done = await this.api
+            .collection('gaia_ticket')
+            .where('conductor_id.machine_id', '=', id)
+            .where('state', '=', 'done')
+            .where('cleaned_up', '=', '0')
+            .fields(fields)
+            .page(100)
+            .list();
+        const closed = await this.api
+            .collection('gaia_ticket')
+            .where('conductor_id.machine_id', '=', id)
+            .where('closed', '=', '1')
+            .where('cleaned_up', '=', '0')
+            .fields(fields)
+            .page(100)
+            .list();
+        const byUuid = new Map();
+        for (const r of [...done, ...closed]) {
+            byUuid.set(r.id, r);
+        }
+        return Promise.all([...byUuid.values()].map(async (r) => ({
+            ticketUuid: r.id,
+            branchName: r.attr('branch_name') ?? '',
+            state: r.attr('state') ?? '',
+            closed: r.attr('closed') ?? false,
+            worktreePath: await this.latestRunWorktree(r.id),
+        })));
+    }
+    async closeTicket(uuid) {
+        const t = Math.floor(Date.now() / 1000);
+        await this.api.update('gaia_ticket', uuid, {
+            attributes: { closed: true, closed_date: t },
+        }); // NO state — the ticket is already done.
+    }
+    async markTicketCleanedUp(uuid) {
+        await this.api.update('gaia_ticket', uuid, {
+            attributes: { cleaned_up: true },
+        }); // NO state/closed — teardown flag only, decoupled from the lifecycle.
+    }
+    /**
+     * Absolute worktree path of the ticket's latest run (highest run id with a
+     * non-empty worktree_path), or '' when none — the cwd the cleanup command
+     * runs in. The conductor persists worktree_path on markRunning, so a done
+     * ticket's run carries the path even after the run closed.
+     */
+    async latestRunWorktree(ticketUuid) {
+        const rows = await this.api
+            .collection('gaia_run')
+            .where('ticket_id.id', '=', ticketUuid)
+            .fields(['worktree_path', 'drupal_internal__id'])
+            .sort('-drupal_internal__id')
+            .page(100)
+            .list();
+        for (const r of rows) {
+            const path = r.attr('worktree_path');
+            if (path) {
+                return path;
+            }
+        }
+        return '';
+    }
+    async resolveTicketByIdentifier(project, identifier) {
+        // Scope by the project uuid: identifiers (GAIA-nnn) are unique per project,
+        // not globally, so a bare identifier filter could match another project's
+        // ticket in a multi-project instance.
+        const projectId = await this.projectUuid(project);
+        const t = await this.api
+            .collection('gaia_ticket')
+            .where('identifier', '=', identifier)
+            .where('project_id.id', '=', projectId)
+            .first();
+        if (!t) {
+            return null;
+        }
+        return { uuid: t.id, title: t.attr('title') ?? '' };
+    }
+    projectUuidCache = new Map();
+    async projectUuid(name) {
+        // A project's name→uuid never changes, so cache it: gatherBatch resolves
+        // many identifiers per `gaia deployment tickets` call, each of which would
+        // otherwise re-fetch the same project.
+        const cached = this.projectUuidCache.get(name);
+        if (cached) {
+            return cached;
+        }
+        const p = await this.api
+            .collection('gaia_project')
+            .where('name', '=', name)
+            .first();
+        if (!p) {
+            throw new Error(`gaia project "${name}" not found`);
+        }
+        this.projectUuidCache.set(name, p.id);
+        return p.id;
+    }
+}
+export function drupalRemote() {
+    return {
+        kind: 'remote',
+        id: 'drupal',
+        requiredModules: [],
+        async createRemote(config) {
+            const http = createHttpClient();
+            const auth = await resolveAuth({
+                baseUrl: config.site.base_url,
+                plugins: config.plugins ?? [],
+                http,
+                now: Date.now,
+                // stateDir omitted → dropsh defaultStateDir() (~/.config/dropsh)
+            });
+            return new DrupalGaiaRemote(createJsonApiClient({
+                baseUrl: config.site.base_url,
+                prefix: config.site.jsonapi_prefix,
+                http,
+                auth: auth,
+            }));
+        },
+    };
+}
+export default drupalRemote;

package/dist/src/preset.d.ts

@@ -0,0 +1,2 @@
+import type { Preset } from '@gaia-ai/conductor/contract';
+export declare const remotes: Preset['remotes'];

package/dist/src/preset.js

@@ -0,0 +1,2 @@
+import { drupalRemote } from './index.js';
+export const remotes = (acc) => [...acc, drupalRemote()];

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@gaia-ai/addon-remote-drupal",
+  "version": "0.6.1",
+  "description": "GAIA conductor remote addon: the Drupal/JSON:API control-plane remote.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./preset": "./dist/src/preset.js"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.key-tec.de/keytec/gaia.git",
+    "directory": "gaia-cli/addons/remote-drupal"
+  },
+  "dependencies": {
+    "dropsh": "^0.5.8"
+  },
+  "peerDependencies": {
+    "@gaia-ai/conductor": "^0.6.1",
+    "@gaia-ai/core": "^0.6.1"
+  }
+}