dsh-plugin-jules 0.1.0

package/lib/index.js

@@ -0,0 +1,234 @@
+/**
+ * Google Jules as a harness capability: the `jules_*` tool family lets a model
+ * delegate a coding task to the remote Jules agent, follow it, approve its plan,
+ * and retrieve the diff or pull request it produced.
+ *
+ * The plugin speaks the documented Jules v1alpha REST API directly. The Jules
+ * CLI is deliberately not used: it authenticates through an interactive OAuth
+ * flow in the OS keyring, reads no `JULES_*` environment variable, produces no
+ * machine-readable output, and drives an internal backend rather than the
+ * documented one — none of which survives contact with an unattended harness
+ * process.
+ *
+ * @module dsh-plugin-jules
+ */
+import z from '@deepseek-ai/schemastery';
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment';
+import { JulesClient } from "./client.js";
+import { registerJulesTools } from "./tools.js";
+import { openWatchJournal, orphanNote } from "./journal.js";
+import { registerJulesWatch } from "./watch.js";
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'jules';
+/** The tool registry, and the system prompt the guidance section joins. */
+export const inject = ['tools', 'systemPrompt'];
+/** Credential name read when the configuration does not name another one. */
+export const DEFAULT_API_KEY_ENV = 'JULES_API_KEY';
+/** API root. Jules exposes one documented version, `v1alpha`. */
+export const DEFAULT_BASE_URL = 'https://jules.googleapis.com/v1alpha';
+/** Where a user creates the API key this plugin reads. */
+export const API_KEY_URL = 'https://jules.google.com/settings';
+/** Default per-request deadline. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/** Default page size for list calls; the service default is 30. */
+export const DEFAULT_PAGE_SIZE = 30;
+/** Largest page size the service accepts. */
+export const MAX_PAGE_SIZE = 100;
+/** Default cap on a diff returned by `jules_patch`. */
+export const DEFAULT_MAX_PATCH_BYTES = 200_000;
+/** Default wait budget for `jules_wait`. */
+export const DEFAULT_WAIT_MS = 120_000;
+/** Largest wait budget a caller may request. */
+export const MAX_WAIT_MS = 300_000;
+/** Delay between two `jules_wait` status polls. */
+export const DEFAULT_POLL_INTERVAL_MS = 5_000;
+/** Pages of activities one read may walk. */
+export const DEFAULT_MAX_ACTIVITY_PAGES = 10;
+/** Default background watch budget for `jules_watch`. */
+export const DEFAULT_WATCH_MS = 1_800_000;
+/** Largest background watch budget a caller may request. */
+export const MAX_WATCH_MS = 7_200_000;
+/** Delay between two background watch polls. */
+export const DEFAULT_WATCH_POLL_INTERVAL_MS = 15_000;
+/** Retry attempts for a rate-limited or failing request. */
+export const DEFAULT_RETRY_MAX_ATTEMPTS = 4;
+/** First backoff step for a retried request. */
+export const DEFAULT_RETRY_BASE_DELAY_MS = 1_000;
+/** Ceiling for one backoff step. */
+export const DEFAULT_RETRY_MAX_DELAY_MS = 30_000;
+/** Schemastery configuration for loader defaults and the generated config catalog. */
+export const Config = z.object({
+    apiKey: z.string().role('secret'),
+    apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
+    baseURL: z.string().default(DEFAULT_BASE_URL),
+    defaultSource: z.string(),
+    requestTimeoutMs: z.number().step(1).min(1).default(DEFAULT_REQUEST_TIMEOUT_MS),
+    defaultPageSize: z.number().step(1).min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE),
+    maxPageSize: z.number().step(1).min(1).max(MAX_PAGE_SIZE).default(MAX_PAGE_SIZE),
+    maxPatchBytes: z.number().step(1).min(1_000).default(DEFAULT_MAX_PATCH_BYTES),
+    waitDefaultMs: z.number().step(1).min(1_000).default(DEFAULT_WAIT_MS),
+    waitMaxMs: z.number().step(1).min(1_000).default(MAX_WAIT_MS),
+    pollIntervalMs: z.number().step(1).min(250).default(DEFAULT_POLL_INTERVAL_MS),
+    maxActivityPages: z.number().step(1).min(1).default(DEFAULT_MAX_ACTIVITY_PAGES),
+    enableWatch: z.boolean().default(true),
+    watchDefaultMs: z.number().step(1).min(30_000).default(DEFAULT_WATCH_MS),
+    watchMaxMs: z.number().step(1).min(30_000).default(MAX_WATCH_MS),
+    watchPollIntervalMs: z.number().step(1).min(250).default(DEFAULT_WATCH_POLL_INTERVAL_MS),
+    watchSettleOnMessage: z.boolean().default(true),
+    retryMaxAttempts: z.number().step(1).min(1).default(DEFAULT_RETRY_MAX_ATTEMPTS),
+    retryBaseDelayMs: z.number().step(1).min(1).default(DEFAULT_RETRY_BASE_DELAY_MS),
+    retryMaxDelayMs: z.number().step(1).min(1).default(DEFAULT_RETRY_MAX_DELAY_MS),
+});
+/** Model guidance placed beside the subagent instructions. */
+export const JULES_PROMPT = 'Jules is a remote coding agent reachable through the jules_* tools. It runs asynchronously in the cloud on its own clone of a '
+    + 'repository, so a session keeps working after your turn ends. '
+    + 'DO NOT POLL. jules_create starts a session and returns its id; jules_watch registers a background watch and returns a job id; '
+    + 'then END YOUR TURN and get on with something else. The watch notice wakes you when the session finishes, fails, needs a plan '
+    + 'decision, or posts a message, and job_output reads what happened. Nothing needs checking in between — waiting is the watcher\'s '
+    + 'job, not yours, and a status call that returns what you already saw has cost a turn and bought nothing. '
+    + 'jules_wait is the same wait held open in the foreground; use it only when you genuinely have nothing else to do. '
+    + 'jules_status is for confirming an action you just took, following up a notice, or answering the user when they ask about a '
+    + 'session — never for waiting. '
+    + 'The rest: jules_sources lists the repositories Jules may work in; jules_activities reads the event log, for diagnosing a stall '
+    + 'rather than polling; jules_approve_plan releases a plan you have reviewed; jules_send_message answers or corrects the agent; '
+    + 'jules_patch returns the unified diff, in slices when it is large. '
+    + 'Ask for requirePlanApproval when a task will change existing code, then review the plan before approving it. '
+    + 'Prefer finishing small work here; delegate a task that is long, independent, or better done in a clean checkout, and do not '
+    + 'open several sessions for one task because the service throttles concurrent creation.';
+/**
+ * Complete every optional field and reject combinations the schema cannot express.
+ * @param config - the validated configuration section.
+ * @returns the fully defaulted bounds the plugin runs with.
+ */
+function resolveConfig(config) {
+    const resolved = {
+        apiKey: config.apiKey,
+        defaultSource: config.defaultSource,
+        apiKeyEnv: config.apiKeyEnv ?? DEFAULT_API_KEY_ENV,
+        baseURL: (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/+$/, ''),
+        requestTimeoutMs: config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+        defaultPageSize: config.defaultPageSize ?? DEFAULT_PAGE_SIZE,
+        maxPageSize: config.maxPageSize ?? MAX_PAGE_SIZE,
+        maxPatchBytes: config.maxPatchBytes ?? DEFAULT_MAX_PATCH_BYTES,
+        waitDefaultMs: config.waitDefaultMs ?? DEFAULT_WAIT_MS,
+        waitMaxMs: config.waitMaxMs ?? MAX_WAIT_MS,
+        pollIntervalMs: config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+        maxActivityPages: config.maxActivityPages ?? DEFAULT_MAX_ACTIVITY_PAGES,
+        enableWatch: config.enableWatch ?? true,
+        watchDefaultMs: config.watchDefaultMs ?? DEFAULT_WATCH_MS,
+        watchMaxMs: config.watchMaxMs ?? MAX_WATCH_MS,
+        watchPollIntervalMs: config.watchPollIntervalMs ?? DEFAULT_WATCH_POLL_INTERVAL_MS,
+        watchSettleOnMessage: config.watchSettleOnMessage ?? true,
+        retryMaxAttempts: config.retryMaxAttempts ?? DEFAULT_RETRY_MAX_ATTEMPTS,
+        retryBaseDelayMs: config.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS,
+        retryMaxDelayMs: config.retryMaxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS,
+    };
+    if (resolved.defaultPageSize > resolved.maxPageSize) {
+        throw new Error('jules: defaultPageSize must not exceed maxPageSize');
+    }
+    if (resolved.waitDefaultMs > resolved.waitMaxMs) {
+        throw new Error('jules: waitDefaultMs must not exceed waitMaxMs');
+    }
+    if (resolved.watchDefaultMs > resolved.watchMaxMs) {
+        throw new Error('jules: watchDefaultMs must not exceed watchMaxMs');
+    }
+    if (resolved.retryBaseDelayMs > resolved.retryMaxDelayMs) {
+        throw new Error('jules: retryBaseDelayMs must not exceed retryMaxDelayMs');
+    }
+    if (!URL.canParse(resolved.baseURL)) {
+        throw new Error(`jules: baseURL must be an absolute URL, received ${JSON.stringify(resolved.baseURL)}`);
+    }
+    return resolved;
+}
+/**
+ * Register the Jules tool family and its model guidance.
+ * @param ctx - plugin context supplying the tool registry and credential seam.
+ * @param config - validated configuration section.
+ */
+export function apply(ctx, config) {
+    const resolved = resolveConfig(config);
+    const apiKeyEnv = credentialRef(resolved.apiKeyEnv);
+    const literalApiKey = resolved.apiKey !== undefined && resolved.apiKey.length > 0
+        ? resolved.apiKey
+        : undefined;
+    const client = new JulesClient({
+        resolveApiKey: async () => {
+            if (literalApiKey !== undefined)
+                return literalApiKey;
+            const credentials = ctx.get('credentials');
+            if (credentials !== undefined) {
+                const record = await credentials.resolve(apiKeyEnv);
+                if (record !== undefined && record.value.length > 0)
+                    return record.value;
+            }
+            // Without the credential seam, the launch environment is the whole
+            // credential plane — the same fallback the in-box providers take.
+            const ambient = launchEnvironmentOf(ctx).get(apiKeyEnv);
+            return ambient !== undefined && ambient.value.length > 0 ? ambient.value : undefined;
+        },
+        baseURL: resolved.baseURL,
+        requestTimeoutMs: resolved.requestTimeoutMs,
+        defaultPageSize: resolved.defaultPageSize,
+        maxPageSize: resolved.maxPageSize,
+        retry: {
+            maxAttempts: resolved.retryMaxAttempts,
+            baseDelayMs: resolved.retryBaseDelayMs,
+            maxDelayMs: resolved.retryMaxDelayMs,
+        },
+    });
+    registerJulesTools(ctx, client, {
+        maxPatchBytes: resolved.maxPatchBytes,
+        waitDefaultMs: resolved.waitDefaultMs,
+        waitMaxMs: resolved.waitMaxMs,
+        pollIntervalMs: resolved.pollIntervalMs,
+        maxActivityPages: resolved.maxActivityPages,
+        settleOnMessage: resolved.watchSettleOnMessage,
+        defaultSource: resolved.defaultSource ?? '',
+    });
+    // Watches are process-local and cannot be restored before an agent exists to
+    // own one, so the journal only preserves what was in flight.
+    //
+    // Injected rather than read with ctx.get(): activation here is
+    // service-availability driven and does not follow row order, so the storage
+    // domain can arrive after this plugin applies. Reading it eagerly raced and
+    // silently disabled the journal — no records, and no error either.
+    let journal;
+    // Sessions this process is actively watching. The note is about watches that
+    // survived a restart, and a watch running right now is not one of them.
+    const live = new Set();
+    ctx.inject(['storageDomain'], (storageCtx) => {
+        void openWatchJournal(storageCtx)
+            .then((opened) => { journal = opened; })
+            .catch((error) => {
+            storageCtx.logger.warn(`jules: could not open the watch journal: ${String(error)}`);
+        });
+    });
+    if (resolved.enableWatch) {
+        // Registered through an optional injection: a composition without the job
+        // registry still gets the other nine tools instead of holding the whole
+        // plugin PENDING on a service it may never provide.
+        const watchConfig = {
+            pollIntervalMs: resolved.watchPollIntervalMs,
+            defaultMs: resolved.watchDefaultMs,
+            maxMs: resolved.watchMaxMs,
+            maxActivityPages: resolved.maxActivityPages,
+            settleOnMessage: resolved.watchSettleOnMessage,
+        };
+        ctx.inject(['jobs'], (jobsCtx) => {
+            registerJulesWatch(jobsCtx, client, watchConfig, () => journal, live);
+        });
+    }
+    ctx.systemPrompt.section({
+        name: 'tool:jules',
+        // Borrows the subagent slot deliberately. The order table is a fixed set of
+        // positions owned by particular tool families, and Jules is the same kind of
+        // thing a subagent is — a delegation target — so its guidance belongs beside
+        // those instructions rather than in an unrelated slot. Equal orders fall back
+        // to name order, which is stable.
+        order: ctx.systemPrompt.getSectionOrder('TOOL_SUBAGENT'),
+        // Evaluated per assembly, so the orphan note appears the moment the plugin
+        // loads after a restart and disappears as watches are re-armed.
+        text: () => JULES_PROMPT + orphanNote((journal?.pending() ?? []).filter(record => !live.has(record.session))),
+    });
+}

package/lib/journal.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The durable half of watching: a record of what was being watched.
+ *
+ * Background jobs are process-local. The registry holds them in memory and
+ * tears every one down when its service disposes, so a harness restart ends
+ * every watch silently — while the Jules sessions themselves carry on in
+ * Google's cloud, because they were never ours to begin with.
+ *
+ * Nothing can bring the job back. A job needs a live owning agent to receive a
+ * completion notice, and at plugin load there is no agent, so this journal does
+ * not pretend to restore one. It preserves the *fact* of what was being
+ * watched, which the prompt turns into an instruction to re-arm — and which
+ * clears itself, because an entry is only interesting until the watch budget it
+ * recorded would have run out anyway.
+ *
+ * @module dsh-plugin-jules/journal
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** One armed watch, as it needs to survive a restart. */
+export interface WatchRecord {
+    /** Bare Jules session id. */
+    session: string;
+    /** Epoch ms the watch was armed. */
+    startedAt: number;
+    /** Epoch ms after which the watch would have given up on its own. */
+    expiresAt: number;
+}
+/**
+ * The watch journal domain.
+ *
+ * `backup-and-skip` because this is a re-arm hint and nothing more: one unreadable
+ * record must never cost the plugin its load.
+ */
+export declare const julesWatchDomainSpec: {
+    name: string;
+    version: number;
+    invalidRecords: "backup-and-skip";
+    layout: "per-record";
+    tables: {
+        watches: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, WatchRecord>;
+    };
+};
+/**
+ * Records an active watch, so a restart can still say what was in flight.
+ *
+ * Writes never reject. A journal failure costs the restart note, never the
+ * watch, so it must not take down the job that is doing the real work — but it
+ * is logged, because swallowing it silently is exactly how this went unnoticed
+ * for a release.
+ */
+export interface WatchJournal {
+    /** Record a freshly armed watch, replacing any earlier entry for that session. Never rejects. */
+    arm(record: WatchRecord): Promise<void>;
+    /** Forget one session, once its watch has settled for any reason. Never rejects. */
+    release(session: string): Promise<void>;
+    /** Every record whose watch was still running, oldest first. */
+    pending(now?: number): WatchRecord[];
+}
+/**
+ * Describe the watches a restart orphaned.
+ *
+ * A live job cannot exist before an agent does, so the most this can do is tell
+ * the next agent what to re-arm. Returns an empty string when there is nothing
+ * to report, which keeps the prompt section unchanged in the common case.
+ * @param records - records the journal still holds.
+ * @returns the paragraph to append to the model guidance, or ''.
+ */
+export declare function orphanNote(records: readonly WatchRecord[]): string;
+/**
+ * Open the journal over the mounted storage domain.
+ *
+ * A composition without the domain form still gets the whole tool family — it
+ * simply loses the ability to say what was being watched before a restart, which
+ * is why this answers `undefined` rather than failing the plugin.
+ * @param ctx - plugin context supplying the storage domain form.
+ * @returns the journal, or undefined when no storage is mounted.
+ */
+export declare function openWatchJournal(ctx: Context): Promise<WatchJournal | undefined>;

package/lib/journal.js

@@ -0,0 +1,110 @@
+/**
+ * The durable half of watching: a record of what was being watched.
+ *
+ * Background jobs are process-local. The registry holds them in memory and
+ * tears every one down when its service disposes, so a harness restart ends
+ * every watch silently — while the Jules sessions themselves carry on in
+ * Google's cloud, because they were never ours to begin with.
+ *
+ * Nothing can bring the job back. A job needs a live owning agent to receive a
+ * completion notice, and at plugin load there is no agent, so this journal does
+ * not pretend to restore one. It preserves the *fact* of what was being
+ * watched, which the prompt turns into an instruction to re-arm — and which
+ * clears itself, because an entry is only interesting until the watch budget it
+ * recorded would have run out anyway.
+ *
+ * @module dsh-plugin-jules/journal
+ */
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+import { z } from 'zod';
+/** The durable shape of one record, validated at open and on every write. */
+const watchRecord = z.object({
+    session: z.string(),
+    startedAt: z.number().int().nonnegative(),
+    expiresAt: z.number().int().nonnegative(),
+});
+/**
+ * The watch journal domain.
+ *
+ * `backup-and-skip` because this is a re-arm hint and nothing more: one unreadable
+ * record must never cost the plugin its load.
+ */
+export const julesWatchDomainSpec = defineDomain({
+    name: 'jules_watches',
+    version: 1,
+    invalidRecords: 'backup-and-skip',
+    layout: 'per-record',
+    tables: { watches: domainTable(watchRecord) },
+});
+/**
+ * Describe the watches a restart orphaned.
+ *
+ * A live job cannot exist before an agent does, so the most this can do is tell
+ * the next agent what to re-arm. Returns an empty string when there is nothing
+ * to report, which keeps the prompt section unchanged in the common case.
+ * @param records - records the journal still holds.
+ * @returns the paragraph to append to the model guidance, or ''.
+ */
+export function orphanNote(records) {
+    if (records.length === 0)
+        return '';
+    const ids = records.map(record => record.session).join(', ');
+    return '\n\nNote: background watches do not survive a harness restart, and '
+        + (records.length === 1 ? 'one watch was' : records.length + ' watches were')
+        + ' still armed when this harness last stopped: ' + ids + '. '
+        + 'The Jules sessions themselves kept running in the cloud. Re-arm the ones you still care about with '
+        + 'jules_watch; a session that has since finished needs only a jules_status.';
+}
+/**
+ * Open the journal over the mounted storage domain.
+ *
+ * A composition without the domain form still gets the whole tool family — it
+ * simply loses the ability to say what was being watched before a restart, which
+ * is why this answers `undefined` rather than failing the plugin.
+ * @param ctx - plugin context supplying the storage domain form.
+ * @returns the journal, or undefined when no storage is mounted.
+ */
+export async function openWatchJournal(ctx) {
+    const storageDomain = ctx.get('storageDomain');
+    if (storageDomain === undefined)
+        return undefined;
+    const domain = await storageDomain.open(julesWatchDomainSpec);
+    ctx.effect(() => () => domain.close(), 'jules.watchJournal.close');
+    const table = domain.table('watches');
+    const warn = (message, error) => {
+        ctx.logger.warn(`jules: ${message}: ${String(error)}`);
+    };
+    return {
+        async arm(record) {
+            try {
+                await table.put(record.session, record);
+            }
+            catch (error) {
+                warn(`could not record the watch for session ${record.session}`, error);
+            }
+        },
+        async release(session) {
+            try {
+                await table.delete(session);
+            }
+            catch (error) {
+                warn(`could not release the watch for session ${session}`, error);
+            }
+        },
+        pending(now = Date.now()) {
+            const live = [];
+            for (const [, record] of table.entries()) {
+                if (record.expiresAt > now)
+                    live.push(record);
+                // Expired entries are no longer interesting, so drop them rather than
+                // let a dead watch keep reporting itself forever.
+                else {
+                    table.delete(record.session).catch((error) => {
+                        warn(`could not prune the expired watch for session ${record.session}`, error);
+                    });
+                }
+            }
+            return live.sort((left, right) => left.startedAt - right.startedAt);
+        },
+    };
+}

package/lib/tools.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The model-facing `jules_*` tool family.
+ *
+ * Every tool returns a canonical value described by its own output schema and
+ * renders that value to text separately, so a caller that needs an id or a
+ * state never has to parse the prose.
+ *
+ * @module dsh-plugin-jules/tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { JulesClient } from './client.ts';
+/** Bounds the tool family applies to its own inputs. */
+export interface JulesToolConfig {
+    /** Largest unified diff `jules_patch` will return. */
+    maxPatchBytes: number;
+    /** Wait budget `jules_wait` uses when the caller does not choose one. */
+    waitDefaultMs: number;
+    /** Upper bound a caller may raise the wait budget to. */
+    waitMaxMs: number;
+    /** Delay between two status polls inside `jules_wait`. */
+    pollIntervalMs: number;
+    /** Pages of activities a single read may walk. */
+    maxActivityPages: number;
+    /** End a wait or watch when the agent posts a message, not only on a state change. */
+    settleOnMessage: boolean;
+    /** Repository `jules_create` targets when the call omits one, as `owner/repo`. */
+    defaultSource: string;
+}
+/**
+ * Register every `jules_*` tool.
+ *
+ * Concurrency classification is a rule, not a per-tool judgement: every
+ * read-only tool declares itself concurrency-safe so sibling calls may overlap,
+ * and exactly the three that ask the service to change something —
+ * `jules_create`, `jules_approve_plan`, `jules_send_message` — leave it unset so
+ * the pipeline serializes them against their siblings. Marking a mutating tool
+ * safe would let two approvals race, and marking a reader unsafe would make a
+ * batch of status checks run one at a time for no reason.
+ * @param ctx - plugin context supplying the tool registry.
+ * @param client - the configured Jules client.
+ * @param config - bounds applied to tool inputs.
+ */
+export declare function registerJulesTools(ctx: Context, client: JulesClient, config: JulesToolConfig): void;