dsh-plugin-jules 0.1.0

package/lib/views.js

@@ -0,0 +1,438 @@
+/**
+ * Projections from Jules wire objects to the canonical values the tools return,
+ * and the text those values render to.
+ *
+ * Every projected object carries a value for each declared member: an absent
+ * optional scalar becomes `''` and an absent list becomes `[]`. The canonical
+ * value therefore stays lossless JSON with a fixed shape, and the renderer — not
+ * the model — decides what an empty value means.
+ *
+ * @module dsh-plugin-jules/views
+ */
+import { activityKind, shortSourceName } from "./types.js";
+/**
+ * Join a plan's steps into display lines.
+ * @param plan - the plan, when one was generated.
+ * @returns one line per step.
+ */
+function planLines(plan) {
+    const steps = plan?.steps ?? [];
+    return steps.map((step, index) => {
+        const ordinal = step.index ?? index + 1;
+        const title = step.title ?? 'untitled step';
+        return step.description === undefined || step.description.length === 0
+            ? `${ordinal}. ${title}`
+            : `${ordinal}. ${title} — ${step.description}`;
+    });
+}
+/**
+ * Describe one artifact without reproducing its payload.
+ * @param artifact - one artifact from an activity.
+ * @returns a short descriptor.
+ */
+function artifactSummary(artifact) {
+    if (artifact.changeSet !== undefined) {
+        const patch = artifact.changeSet.gitPatch?.unidiffPatch ?? '';
+        const files = patch.length === 0 ? 0 : patch.split('\n').filter(line => line.startsWith('diff --git ')).length;
+        const bytes = patch.length;
+        return `changeSet: ${files} file(s), ${bytes} byte(s) of unified diff`;
+    }
+    if (artifact.bashOutput !== undefined) {
+        const command = artifact.bashOutput.command ?? 'command';
+        const exit = artifact.bashOutput.exitCode;
+        return `bashOutput: ${command}${exit === undefined ? '' : ` (exit ${exit})`}`;
+    }
+    if (artifact.media !== undefined) {
+        return `media: ${artifact.media.mimeType ?? 'application/octet-stream'}`;
+    }
+    return 'unknown artifact';
+}
+/**
+ * Read the one human-readable line an activity carries.
+ * @param activity - one activity from the log.
+ * @returns the message, progress text, or failure reason.
+ */
+export function activitySummary(activity) {
+    if (activity.planGenerated !== undefined) {
+        const steps = planLines(activity.planGenerated.plan);
+        return steps.length === 0 ? 'Plan generated.' : `Plan generated with ${steps.length} step(s).`;
+    }
+    if (activity.planApproved !== undefined)
+        return `Plan ${activity.planApproved.planId ?? ''} approved.`.trim();
+    if (activity.userMessaged !== undefined)
+        return activity.userMessaged.userMessage ?? 'User message.';
+    if (activity.agentMessaged !== undefined)
+        return activity.agentMessaged.agentMessage ?? 'Agent message.';
+    if (activity.progressUpdated !== undefined) {
+        const title = activity.progressUpdated.title ?? '';
+        const description = activity.progressUpdated.description ?? '';
+        if (title.length > 0 && description.length > 0)
+            return `${title}: ${description}`;
+        return title.length > 0 ? title : description;
+    }
+    if (activity.sessionCompleted !== undefined)
+        return 'Session completed.';
+    if (activity.sessionFailed !== undefined)
+        return `Session failed: ${activity.sessionFailed.reason ?? 'no reason reported'}`;
+    return activity.description ?? 'Unrecognized activity.';
+}
+/**
+ * Project one session into a list row.
+ * @param session - the wire session.
+ * @returns the row value.
+ */
+export function sessionRow(session) {
+    return {
+        id: session.id ?? '',
+        title: session.title ?? '',
+        state: session.state ?? 'STATE_UNSPECIFIED',
+        url: session.url ?? '',
+        source: shortSourceName(session.sourceContext?.source),
+        branch: session.sourceContext?.githubRepoContext?.startingBranch ?? '',
+        createTime: session.createTime ?? '',
+        updateTime: session.updateTime ?? '',
+        pullRequests: (session.outputs ?? []).flatMap(output => output.pullRequest?.url ?? []),
+    };
+}
+/**
+ * Project one session into the full detail view.
+ * @param session - the wire session.
+ * @param activities - the session's event log, when it was read.
+ * @returns the detail value.
+ */
+export function sessionDetail(session, activities = [], options = {}) {
+    const latestPlan = [...activities].reverse()
+        .find(activity => activity.planGenerated !== undefined)?.planGenerated?.plan;
+    const approved = activities.some(activity => activity.planApproved !== undefined);
+    // A plan is pending while the newest plan event is its generation.
+    const lastPlanIndex = activities.findLastIndex(activity => activity.planGenerated !== undefined);
+    const lastApprovalIndex = activities.findLastIndex(activity => activity.planApproved !== undefined);
+    const planPending = lastPlanIndex >= 0 && lastApprovalIndex < lastPlanIndex;
+    const latestCommand = [...activities].reverse()
+        .flatMap(activity => activity.artifacts ?? [])
+        .find(artifact => artifact.bashOutput?.command !== undefined)?.bashOutput?.command ?? '';
+    const pullRequests = (session.outputs ?? []).flatMap(output => output.pullRequest?.url ?? []);
+    const progress = [...activities].reverse()
+        .find(activity => activity.progressUpdated !== undefined)?.progressUpdated;
+    // A session that stops to ask something produces no plan and no progress, so
+    // without this the projection reads as an empty success.
+    const lastMessage = [...activities].reverse()
+        .find(activity => activity.agentMessaged !== undefined)?.agentMessaged?.agentMessage ?? '';
+    return {
+        id: session.id ?? '',
+        title: session.title ?? '',
+        state: session.state ?? 'STATE_UNSPECIFIED',
+        url: session.url ?? '',
+        prompt: session.prompt ?? '',
+        source: shortSourceName(session.sourceContext?.source),
+        branch: session.sourceContext?.githubRepoContext?.startingBranch ?? '',
+        // Evidence first, echo second. The session object omits these inputs on
+        // read, so 'unknown' beats a fabricated 'no'.
+        requirePlanApproval: session.requirePlanApproval === true
+            ? 'yes'
+            : approved || (latestPlan !== undefined && session.state === 'AWAITING_PLAN_APPROVAL')
+                ? 'yes'
+                : session.requirePlanApproval === false
+                    ? 'no'
+                    : 'unknown',
+        autoCreatePr: session.automationMode === 'AUTO_CREATE_PR' || pullRequests.length > 0
+            ? 'yes'
+            : session.automationMode === undefined || session.automationMode === 'AUTOMATION_MODE_UNSPECIFIED'
+                ? 'unknown'
+                : 'no',
+        archived: session.archived === true,
+        createTime: session.createTime ?? '',
+        updateTime: session.updateTime ?? '',
+        planId: latestPlan?.id ?? '',
+        planSteps: planLines(latestPlan),
+        planPending,
+        planApproved: approved,
+        pullRequests,
+        latestCommand,
+        generatedFiles: (session.generatedFiles ?? []).map(file => ({
+            path: file.path ?? '',
+            changeType: file.changeType ?? '',
+            bytes: (file.content ?? '').length,
+        })),
+        approvalConfirmed: options.approvalConfirmed === true,
+        logRead: options.logRead !== false,
+        lastMessage,
+        unchangedForMs: options.unchangedForMs ?? 0,
+        lastProgress: progress === undefined
+            ? ''
+            : [progress.title, progress.description].filter(part => part !== undefined && part.length > 0).join(': '),
+    };
+}
+/**
+ * Project one source into a row.
+ * @param source - the wire source.
+ * @returns the row value.
+ */
+export function sourceRow(source) {
+    const repo = source.githubRepo;
+    return {
+        name: source.name ?? '',
+        owner: repo?.owner ?? '',
+        repo: repo?.repo ?? '',
+        isPrivate: repo?.isPrivate === true,
+        defaultBranch: repo?.defaultBranch?.displayName ?? '',
+        branches: (repo?.branches ?? []).flatMap(branch => branch.displayName ?? []),
+    };
+}
+/**
+ * Project one activity into a row.
+ * @param activity - the wire activity.
+ * @returns the row value.
+ */
+export function activityRow(activity) {
+    return {
+        id: activity.id ?? '',
+        time: activity.createTime ?? '',
+        originator: activity.originator ?? '',
+        kind: activityKind(activity),
+        summary: activitySummary(activity),
+        artifacts: (activity.artifacts ?? []).map(artifactSummary),
+    };
+}
+/**
+ * Find the newest unified diff in an activity log.
+ *
+ * Activities are append-only, so later pages hold later patches; the last
+ * `changeSet` artifact is the state the session finished in.
+ * @param activities - the session's event log, oldest first.
+ * @returns the newest patch and its provenance, or undefined.
+ */
+export function latestPatch(activities) {
+    for (let index = activities.length - 1; index >= 0; index -= 1) {
+        const changeSet = activities[index]?.artifacts?.find(artifact => artifact.changeSet !== undefined)?.changeSet;
+        if (changeSet !== undefined)
+            return changeSet.gitPatch;
+    }
+    return undefined;
+}
+/** Longest agent message the rendered text repeats before pointing at the log. */
+const MESSAGE_DISPLAY_LIMIT = 1200;
+/**
+ * Bound an agent message for display. The canonical value always keeps the full
+ * text; only the rendered card is clipped, because a scoping question can run to
+ * several paragraphs.
+ * @param text - the message to show.
+ * @returns the message, clipped with a pointer to the full log when long.
+ */
+function clipForDisplay(text) {
+    return text.length <= MESSAGE_DISPLAY_LIMIT
+        ? text
+        : text.slice(0, MESSAGE_DISPLAY_LIMIT) + ' [clipped; read the full log with jules_activities]';
+}
+/**
+ * List the paths a unified diff touches.
+ *
+ * The service's `generatedFiles` manifest was empty on every session observed,
+ * so the diff itself is the only reliable statement of what changed.
+ * @param unidiff - the complete unified diff.
+ * @returns one entry per touched path, in diff order.
+ */
+export function patchFiles(unidiff) {
+    const files = [];
+    for (const line of unidiff.split('\n')) {
+        if (!line.startsWith('diff --git '))
+            continue;
+        const match = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
+        const path = match?.[2];
+        if (path !== undefined && !files.includes(path))
+            files.push(path);
+    }
+    return files;
+}
+/** Render a session state with the action it asks for, when it asks for one. */
+function stateLabel(state) {
+    if (state === 'AWAITING_PLAN_APPROVAL')
+        return 'AWAITING_PLAN_APPROVAL (approve or reject the plan)';
+    if (state === 'AWAITING_USER_FEEDBACK')
+        return 'AWAITING_USER_FEEDBACK (the agent asked a question)';
+    return state;
+}
+/**
+ * Render the source list.
+ * @param sources - projected rows.
+ * @returns the model-facing text.
+ */
+export function renderSources(sources) {
+    if (sources.length === 0) {
+        return 'No repositories are connected to Jules. Install the Jules GitHub App at https://jules.google.com first.';
+    }
+    return sources.map((source) => {
+        const visibility = source.isPrivate ? 'private' : 'public';
+        const branch = source.defaultBranch.length > 0 ? ` default=${source.defaultBranch}` : '';
+        return `${source.owner}/${source.repo} (${visibility},${branch}) -> jules_create source=${source.owner}/${source.repo}`;
+    }).join('\n');
+}
+/**
+ * Render session rows as one line each.
+ * @param rows - projected rows.
+ * @param nextPageToken - continuation token, when the page was truncated.
+ * @returns the model-facing text.
+ */
+export function renderSessionRows(rows, nextPageToken) {
+    const head = rows.length === 0 ? 'No Jules sessions matched.' : rows.map((row) => {
+        const parts = [`${row.id}  ${row.state}`];
+        if (row.title.length > 0)
+            parts.push(row.title);
+        if (row.source.length > 0)
+            parts.push(shortSourceName(`sources/github/${row.source}`));
+        if (row.pullRequests.length > 0)
+            parts.push(row.pullRequests.join(' '));
+        if (row.updateTime.length > 0)
+            parts.push(`updated ${row.updateTime}`);
+        return parts.join('  |  ');
+    }).join('\n');
+    return nextPageToken.length === 0 ? head : `${head}\n(nextPageToken: ${nextPageToken})`;
+}
+/**
+ * Render one session in full.
+ * @param detail - the projected detail.
+ * @returns the model-facing text.
+ */
+export function renderSessionDetail(detail) {
+    const lines = [
+        `${detail.title.length > 0 ? detail.title : '(untitled session)'}  [${detail.id}]`,
+        `state: ${stateLabel(detail.state)}`,
+    ];
+    if (!detail.logRead) {
+        // Without this the reader sees an empty plan, no approval, and no progress,
+        // and concludes the session is idle — the opposite of "we could not look".
+        lines.push('warning: the activity log could not be read, so plan, approval, latest command, and messages below are unknown rather than empty. Retry, or read it directly with jules_activities.');
+    }
+    if (detail.approvalConfirmed) {
+        // The phase and the approval disagree in both directions, and the event log
+        // is the one that is right.
+        lines.push('approval confirmed by the planApproved event in the log.');
+        if (detail.state === 'AWAITING_PLAN_APPROVAL') {
+            lines.push('note: the service still reports AWAITING_PLAN_APPROVAL — that field lags its own approval, so trust the event, not the phase.');
+        }
+    }
+    if (detail.unchangedForMs > 0) {
+        // Meets a polling agent where it actually is: the answer it just got is the
+        // one it already had.
+        lines.push(`note: nothing has changed since your last check ${Math.round(detail.unchangedForMs / 1000)}s ago.`
+            + ' Do not keep polling — a jules_watch notice is what tells you something happened.');
+    }
+    if (detail.url.length > 0)
+        lines.push(`url: ${detail.url}`);
+    if (detail.source.length > 0) {
+        lines.push(`repo: ${detail.source}${detail.branch.length > 0 ? ` (branch ${detail.branch})` : ''}`);
+    }
+    else {
+        lines.push('repo: none (repoless session)');
+    }
+    lines.push(`plan approval required: ${detail.requirePlanApproval}`);
+    lines.push(`auto-create PR: ${detail.autoCreatePr}`);
+    if (detail.createTime.length > 0)
+        lines.push(`created: ${detail.createTime}`);
+    if (detail.updateTime.length > 0)
+        lines.push(`updated: ${detail.updateTime}`);
+    if (detail.planSteps.length > 0) {
+        lines.push(`plan${detail.planPending ? ' (awaiting your approval)' : detail.planApproved ? ' (approved)' : ''}:`);
+        lines.push(...detail.planSteps.map(step => `  ${step}`));
+    }
+    if (detail.latestCommand.length > 0)
+        lines.push(`latest command: ${detail.latestCommand}`);
+    if (detail.pullRequests.length > 0)
+        lines.push(...detail.pullRequests.map(url => `pull request: ${url}`));
+    if (detail.generatedFiles.length > 0) {
+        lines.push(`generated files (${detail.generatedFiles.length}):`);
+        lines.push(...detail.generatedFiles.map(file => `  ${file.changeType.length > 0 ? file.changeType : 'changed'} ${file.path}`));
+    }
+    if (detail.lastMessage.length > 0) {
+        lines.push('latest agent message:');
+        lines.push(...clipForDisplay(detail.lastMessage).split('\n').map(line => `  ${line}`));
+    }
+    if (detail.lastProgress.length > 0)
+        lines.push(`latest progress: ${detail.lastProgress}`);
+    if (detail.prompt.length > 0)
+        lines.push(`prompt:\n  ${detail.prompt.replaceAll('\n', '\n  ')}`);
+    return lines.join('\n');
+}
+/**
+ * Render an activity page.
+ * @param rows - projected rows.
+ * @param nextPageToken - continuation token, when the page was truncated.
+ * @returns the model-facing text.
+ */
+export function renderActivities(rows, nextPageToken) {
+    if (rows.length === 0)
+        return 'This session has no activities yet.';
+    const lines = rows.map((row) => {
+        const head = [row.time, row.kind, row.originator].filter(part => part.length > 0).join('  ');
+        const artifacts = row.artifacts.length === 0 ? '' : `\n    artifacts: ${row.artifacts.join('; ')}`;
+        return `${head}\n  ${row.summary.replaceAll('\n', '\n  ')}${artifacts}`;
+    });
+    const body = lines.join('\n');
+    return nextPageToken.length === 0 ? body : `${body}\n(nextPageToken: ${nextPageToken})`;
+}
+/**
+ * Render a wait result.
+ * @param result - the canonical wait value.
+ * @returns the model-facing text.
+ */
+export function renderWait(result) {
+    const outcome = result.timedOut
+        ? `still ${result.state} after ${Math.round(result.waitedMs / 1000)}s`
+        : `reached ${stateLabel(result.state)} after ${Math.round(result.waitedMs / 1000)}s`;
+    const lines = [`session ${result.id}: ${outcome}`];
+    if (result.lastMessage.length > 0) {
+        lines.push('latest agent message:');
+        lines.push(...clipForDisplay(result.lastMessage).split('\n').map(line => `  ${line}`));
+    }
+    if (result.lastProgress.length > 0)
+        lines.push(`latest progress: ${result.lastProgress}`);
+    if (result.planSteps.length > 0) {
+        lines.push('plan:');
+        lines.push(...result.planSteps.map(step => `  ${step}`));
+    }
+    if (result.pullRequests.length > 0)
+        lines.push(...result.pullRequests.map(url => `pull request: ${url}`));
+    if (result.state === 'AWAITING_PLAN_APPROVAL') {
+        lines.push(`next: call jules_approve_plan with session "${result.id}" to let the agent start, or jules_send_message to change the plan.`);
+    }
+    else if (result.state === 'AWAITING_USER_FEEDBACK') {
+        lines.push(`next: read jules_activities for session "${result.id}" and answer with jules_send_message.`);
+    }
+    else if (result.state === 'FAILED') {
+        lines.push(`next: read jules_activities for session "${result.id}" to see the failure reason.`);
+    }
+    else if (result.lastMessage.length > 0 && !result.settled) {
+        lines.push(`next: the agent posted a message — answer it with jules_send_message for session "${result.id}", and watch again if the work is still running.`);
+    }
+    else if (result.timedOut) {
+        lines.push(`next: call jules_wait or jules_status again for session "${result.id}".`);
+    }
+    else if (result.pullRequests.length === 0) {
+        lines.push(`next: call jules_patch with session "${result.id}" to read the change, or jules_status for the full report.`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Render the newest patch, or explain why there is none.
+ * @param result - the canonical patch value.
+ * @returns the model-facing text.
+ */
+export function renderPatch(result) {
+    if (!result.found) {
+        return `Session ${result.id} has no code change yet. Call jules_wait or jules_status first; a changeSet artifact appears only once the agent edits files.`;
+    }
+    const lines = [];
+    if (result.baseCommitId.length > 0)
+        lines.push(`base commit: ${result.baseCommitId}`);
+    if (result.suggestedCommitMessage.length > 0)
+        lines.push(`suggested commit message: ${result.suggestedCommitMessage}`);
+    if (result.files.length > 0) {
+        lines.push(`files (${result.files.length}):`);
+        lines.push(...result.files.map(file => `  ${file}`));
+    }
+    if (result.truncated) {
+        lines.push(`(showing bytes ${result.offset}-${result.offset + result.patch.length} of ${result.bytes}; continue with offset=${result.nextOffset})`);
+    }
+    lines.push(result.patch);
+    return lines.join('\n');
+}

package/lib/watch.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Background watching for Jules sessions.
+ *
+ * A Jules session runs for minutes in Google's cloud, so a turn that blocks on
+ * one wastes the model's time. `jules_watch` instead registers the wait with
+ * `ctx.jobs`: the call returns a job id immediately, the harness keeps polling
+ * out of band, and `dsh-tool-jobs` delivers a completion notice to the owning
+ * agent when the session finishes, fails, or stops to ask something. The model
+ * reads the report with `job_output` on a later step.
+ *
+ * The session state alone is not a completion signal. Jules can post its final
+ * answer as an `agentMessaged` activity and then leave `state` sitting at
+ * `IN_PROGRESS` indefinitely, so the watcher treats the append-only activity
+ * log as authoritative and settles on what the agent did, not only on what the
+ * state field says.
+ *
+ * @module dsh-plugin-jules/watch
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { JulesClient } from './client.ts';
+import type { WatchJournal } from './journal.ts';
+import type { WaitResult } from './views.ts';
+declare module '@deepseek-ai/dsh-jobs' {
+    interface JobKindMap {
+        jules: 'jules';
+    }
+}
+/** Bounds the watcher applies to its own work. */
+export interface JulesWatchConfig {
+    /** Delay between two status polls. */
+    pollIntervalMs: number;
+    /** Watch budget used when the caller does not choose one. */
+    defaultMs: number;
+    /** Largest watch budget a caller may request. */
+    maxMs: number;
+    /** Activity pages one report may walk. */
+    maxActivityPages: number;
+    /** End the watch when the agent posts a message, not only on a state change. */
+    settleOnMessage: boolean;
+}
+/** Why a watch stopped. */
+export type WatchTrigger = 'state' | 'message' | 'completed' | 'failed' | 'timeout';
+/** What one finished watch observed. */
+export interface WatchOutcome {
+    /** Why the watch stopped. */
+    trigger: WatchTrigger;
+    /** Short status detail for the job snapshot status line. */
+    detail: string;
+    /** The full report the model reads back with `job_output`. */
+    report: string;
+    /**
+     * The structured result. `jules_wait` returns this directly, so the
+     * foreground and background paths can never drift apart in what they decide
+     * or in what they report.
+     */
+    wait: WaitResult;
+}
+/** Polling rules for one watch. */
+export type WatchOptions = Pick<JulesWatchConfig, 'pollIntervalMs' | 'maxActivityPages' | 'settleOnMessage'>;
+/**
+ * Poll one session until the agent hands something back, then describe it.
+ *
+ * Separated from the job adapter so the settling rules — which states end a
+ * watch, which activities end it, when the budget expires, and what the report
+ * contains — are testable without a live agent owner or a real job registry.
+ * @param client - the configured Jules client.
+ * @param session - bare session id.
+ * @param targets - states that end the watch.
+ * @param budgetMs - total watch budget.
+ * @param config - polling rules.
+ * @param signal - task-owned cancellation signal.
+ * @returns why the watch stopped and the rendered report.
+ * @throws whatever the client throws, including cancellation.
+ */
+export declare function runWatch(client: JulesClient, session: string, targets: ReadonlySet<string>, budgetMs: number, config: WatchOptions, signal: AbortSignal): Promise<WatchOutcome>;
+/**
+ * Register `jules_watch`.
+ *
+ * Registered through `ctx.inject(['jobs'])` rather than a plugin-level
+ * injection, so a composition without the job registry still gets the rest of
+ * the tool family instead of holding the whole plugin pending forever.
+ * @param ctx - plugin context supplying the job registry.
+ * @param client - the configured Jules client.
+ * @param config - watch budgets and polling bounds.
+ * @param journal - durable record of armed watches, when storage is mounted.
+ */
+export declare function registerJulesWatch(ctx: Context, client: JulesClient, config: JulesWatchConfig, journal: () => WatchJournal | undefined, live: Set<string>): void;