dsh-plugin-jules 0.1.0

package/lib/types.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Wire types for the Jules v1alpha REST API, plus the small amount of
+ * normalization the tools do before they call it.
+ *
+ * Everything here describes what the service sends: Jules omits optional
+ * members rather than sending nulls, so every field a response may omit is
+ * optional. Nothing in this module imports a harness package, which keeps the
+ * API surface testable on its own.
+ *
+ * @module dsh-plugin-jules/types
+ */
+/** Lifecycle state of one Jules session, as the service reports it. */
+export type SessionState = 'STATE_UNSPECIFIED' | 'QUEUED' | 'PLANNING' | 'AWAITING_PLAN_APPROVAL' | 'AWAITING_USER_FEEDBACK' | 'IN_PROGRESS' | 'PAUSED' | 'FAILED' | 'COMPLETED';
+/** States a session reaches before it starts or after it stops working. */
+export declare const SETTLED_STATES: readonly SessionState[];
+/** States that stop the agent until a human or a model answers it. */
+export declare const ATTENTION_STATES: readonly SessionState[];
+/**
+ * States a caller may reasonably wait for; the default `jules_wait` target.
+ *
+ * `PAUSED` is deliberately absent. The reference lists it in the enum and
+ * documents nothing about what a paused session is waiting for or whether
+ * anything resumes it, so treating it as an end to the wait would invent a
+ * contract. A caller who knows better can name it in `until`, and until then a
+ * paused session reports as a wait that ran out rather than one that finished.
+ *
+ * `QUEUED`, `PLANNING` and `IN_PROGRESS` are absent for the obvious reason:
+ * they are the states a wait exists to sit through.
+ */
+export declare const DEFAULT_WAIT_STATES: readonly SessionState[];
+/**
+ * Report whether a session has stopped for good.
+ * @param state - the state the service reported.
+ * @returns whether the session reached a terminal state.
+ */
+export declare function settledState(state: string): boolean;
+/**
+ * Report whether a session is blocked on an answer.
+ * @param state - the state the service reported.
+ * @returns whether the session waits for a human or model decision.
+ */
+export declare function needsAttentionState(state: string): boolean;
+/** One file's worth of output in a `changeSet` artifact. */
+export interface GitPatch {
+    baseCommitId?: string;
+    unidiffPatch?: string;
+    suggestedCommitMessage?: string;
+}
+/** A code change the agent produced. */
+export interface ChangeSet {
+    source?: string;
+    gitPatch?: GitPatch;
+}
+/** A shell command the agent ran and what it printed. */
+export interface BashOutput {
+    command?: string;
+    output?: string;
+    exitCode?: number;
+}
+/** Base64 media the agent attached, such as a screenshot. */
+export interface Media {
+    mimeType?: string;
+    data?: string;
+}
+/** One thing an activity produced; exactly one member is present. */
+export interface Artifact {
+    changeSet?: ChangeSet;
+    bashOutput?: BashOutput;
+    media?: Media;
+}
+/** One step of a generated plan. */
+export interface PlanStep {
+    id?: string;
+    index?: number;
+    title?: string;
+    description?: string;
+}
+/** The plan a session is executing. */
+export interface Plan {
+    id?: string;
+    steps?: PlanStep[];
+    createTime?: string;
+}
+/** One entry in a session's event log; exactly one event member is present. */
+export interface Activity {
+    name?: string;
+    id?: string;
+    originator?: string;
+    description?: string;
+    createTime?: string;
+    artifacts?: Artifact[];
+    planGenerated?: {
+        plan?: Plan;
+    };
+    planApproved?: {
+        planId?: string;
+    };
+    userMessaged?: {
+        userMessage?: string;
+    };
+    agentMessaged?: {
+        agentMessage?: string;
+    };
+    progressUpdated?: {
+        title?: string;
+        description?: string;
+    };
+    sessionCompleted?: Record<string, never>;
+    sessionFailed?: {
+        reason?: string;
+    };
+}
+/** A pull request the session opened. */
+export interface PullRequest {
+    url?: string;
+    title?: string;
+    description?: string;
+    baseRef?: string;
+    headRef?: string;
+}
+/** One deliverable of a finished session. */
+export interface SessionOutput {
+    pullRequest?: PullRequest;
+}
+/** A file the session produced, in full or as added lines. */
+export interface GeneratedFile {
+    path?: string;
+    changeType?: string;
+    content?: string;
+}
+/** The repository a source points at. */
+export interface GithubRepo {
+    owner?: string;
+    repo?: string;
+    isPrivate?: boolean;
+    defaultBranch?: {
+        displayName?: string;
+    };
+    branches?: {
+        displayName?: string;
+    }[];
+}
+/** A repository connected to Jules through the GitHub App. */
+export interface Source {
+    name?: string;
+    id?: string;
+    githubRepo?: GithubRepo;
+}
+/** One session, as `/sessions/{id}` returns it. */
+export interface Session {
+    name?: string;
+    id?: string;
+    prompt?: string;
+    title?: string;
+    state?: SessionState;
+    url?: string;
+    sourceContext?: {
+        source?: string;
+        githubRepoContext?: {
+            startingBranch?: string;
+            workingBranch?: string;
+        };
+    };
+    requirePlanApproval?: boolean;
+    automationMode?: string;
+    outputs?: SessionOutput[];
+    createTime?: string;
+    updateTime?: string;
+    generatedFiles?: GeneratedFile[];
+    archived?: boolean;
+}
+/** A page of sources. */
+export interface ListSourcesResponse {
+    sources?: Source[];
+    nextPageToken?: string;
+}
+/** A page of sessions. */
+export interface ListSessionsResponse {
+    sessions?: Session[];
+    nextPageToken?: string;
+}
+/** A page of activities. */
+export interface ListActivitiesResponse {
+    activities?: Activity[];
+    nextPageToken?: string;
+}
+/** What `jules_create` sends. `sourceContext` is omitted for a repoless session. */
+export interface CreateSessionRequest {
+    prompt: string;
+    title?: string;
+    sourceContext?: {
+        source: string;
+        githubRepoContext?: {
+            startingBranch?: string;
+        };
+    };
+    requirePlanApproval?: boolean;
+    automationMode?: string;
+}
+/**
+ * Reduce any session reference a model may produce to the bare id the API
+ * paths use: `123`, `sessions/123`, or the `jules.google.com/session/123`
+ * URL all become `123`.
+ * @param reference - session id, resource name, or session URL.
+ * @returns the bare session id.
+ * @throws {TypeError} when the reference carries no id.
+ */
+export declare function sessionIdOf(reference: string): string;
+/**
+ * Accept the three spellings of a connected repository and produce the
+ * resource name the API expects: `owner/repo` and `github/owner/repo` both
+ * become `sources/github/owner/repo`.
+ * @param reference - `owner/repo`, `github/owner/repo`, or the full resource name.
+ * @returns the canonical source resource name.
+ * @throws {TypeError} when the reference is not a two-part repository id.
+ */
+export declare function sourceNameOf(reference: string): string;
+/**
+ * Render a source resource name back as `owner/repo` for display, leaving an
+ * unrecognized name untouched.
+ * @param name - the source resource name.
+ * @returns the short repository reference.
+ */
+export declare function shortSourceName(name: string | undefined): string;
+/**
+ * Identify which event an activity carries.
+ * @param activity - one activity from the log.
+ * @returns the event member name, or `'unknown'` when none is present.
+ */
+export declare function activityKind(activity: Activity): string;

package/lib/types.js

@@ -0,0 +1,128 @@
+/**
+ * Wire types for the Jules v1alpha REST API, plus the small amount of
+ * normalization the tools do before they call it.
+ *
+ * Everything here describes what the service sends: Jules omits optional
+ * members rather than sending nulls, so every field a response may omit is
+ * optional. Nothing in this module imports a harness package, which keeps the
+ * API surface testable on its own.
+ *
+ * @module dsh-plugin-jules/types
+ */
+/** States a session reaches before it starts or after it stops working. */
+export const SETTLED_STATES = ['COMPLETED', 'FAILED'];
+/** States that stop the agent until a human or a model answers it. */
+export const ATTENTION_STATES = ['AWAITING_PLAN_APPROVAL', 'AWAITING_USER_FEEDBACK'];
+/**
+ * States a caller may reasonably wait for; the default `jules_wait` target.
+ *
+ * `PAUSED` is deliberately absent. The reference lists it in the enum and
+ * documents nothing about what a paused session is waiting for or whether
+ * anything resumes it, so treating it as an end to the wait would invent a
+ * contract. A caller who knows better can name it in `until`, and until then a
+ * paused session reports as a wait that ran out rather than one that finished.
+ *
+ * `QUEUED`, `PLANNING` and `IN_PROGRESS` are absent for the obvious reason:
+ * they are the states a wait exists to sit through.
+ */
+export const DEFAULT_WAIT_STATES = [...SETTLED_STATES, ...ATTENTION_STATES];
+/**
+ * Report whether a session has stopped for good.
+ * @param state - the state the service reported.
+ * @returns whether the session reached a terminal state.
+ */
+export function settledState(state) {
+    return SETTLED_STATES.includes(state);
+}
+/**
+ * Report whether a session is blocked on an answer.
+ * @param state - the state the service reported.
+ * @returns whether the session waits for a human or model decision.
+ */
+export function needsAttentionState(state) {
+    return ATTENTION_STATES.includes(state);
+}
+/** The identifying part of a session reference, accepted in any of its forms. */
+const SESSION_ID_PATTERN = /^sessions\/([^/]+)$/;
+/** A reference that points at an activity rather than at its session. */
+const ACTIVITY_REFERENCE_PATTERN = /^sessions\/[^/]+\/activities/;
+/**
+ * Reduce any session reference a model may produce to the bare id the API
+ * paths use: `123`, `sessions/123`, or the `jules.google.com/session/123`
+ * URL all become `123`.
+ * @param reference - session id, resource name, or session URL.
+ * @returns the bare session id.
+ * @throws {TypeError} when the reference carries no id.
+ */
+export function sessionIdOf(reference) {
+    const trimmed = reference.trim().replace(/\/+$/, '');
+    if (trimmed.length === 0)
+        throw new TypeError('a Jules session reference must not be empty');
+    // Checked before the session forms: \`sessions/1/activities/2\` would otherwise
+    // read as the session id \`1/activities/2\` and reach the API as a 404.
+    if (ACTIVITY_REFERENCE_PATTERN.test(trimmed)) {
+        throw new TypeError(`${JSON.stringify(reference)} names an activity, not a session`);
+    }
+    const fromUrl = /jules\.google\.com\/session\/([^/?#]+)/.exec(trimmed);
+    if (fromUrl?.[1] !== undefined)
+        return fromUrl[1];
+    const fromName = SESSION_ID_PATTERN.exec(trimmed);
+    if (fromName?.[1] !== undefined && fromName[1].length > 0)
+        return fromName[1];
+    return trimmed;
+}
+/**
+ * Accept the three spellings of a connected repository and produce the
+ * resource name the API expects: `owner/repo` and `github/owner/repo` both
+ * become `sources/github/owner/repo`.
+ * @param reference - `owner/repo`, `github/owner/repo`, or the full resource name.
+ * @returns the canonical source resource name.
+ * @throws {TypeError} when the reference is not a two-part repository id.
+ */
+export function sourceNameOf(reference) {
+    const trimmed = reference.trim();
+    if (trimmed.startsWith('sources/')) {
+        const rest = trimmed.slice('sources/'.length);
+        return rest.startsWith('github/') ? trimmed : `sources/github/${rest}`;
+    }
+    const parts = trimmed.replace(/^github\//, '').split('/');
+    if (parts.length !== 2 || parts[0] === undefined || parts[1] === undefined
+        || parts[0].length === 0 || parts[1].length === 0) {
+        throw new TypeError(`${JSON.stringify(reference)} is not a repository reference; use "owner/repo" or "sources/github/owner/repo"`);
+    }
+    return `sources/github/${parts[0]}/${parts[1]}`;
+}
+/**
+ * Render a source resource name back as `owner/repo` for display, leaving an
+ * unrecognized name untouched.
+ * @param name - the source resource name.
+ * @returns the short repository reference.
+ */
+export function shortSourceName(name) {
+    if (name === undefined)
+        return '';
+    const match = /^sources\/github\/(.+)$/.exec(name);
+    return match?.[1] ?? name;
+}
+/**
+ * Identify which event an activity carries.
+ * @param activity - one activity from the log.
+ * @returns the event member name, or `'unknown'` when none is present.
+ */
+export function activityKind(activity) {
+    if (activity.planGenerated !== undefined)
+        return 'planGenerated';
+    if (activity.planApproved !== undefined)
+        return 'planApproved';
+    if (activity.userMessaged !== undefined)
+        return 'userMessaged';
+    if (activity.agentMessaged !== undefined)
+        return 'agentMessaged';
+    if (activity.progressUpdated !== undefined)
+        return 'progressUpdated';
+    if (activity.sessionCompleted !== undefined)
+        return 'sessionCompleted';
+    if (activity.sessionFailed !== undefined)
+        return 'sessionFailed';
+    return 'unknown';
+}

package/lib/views.d.ts

@@ -0,0 +1,240 @@
+/**
+ * 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 type { Activity, GitPatch, Session, Source } from './types.ts';
+/** One row of `jules_sources`. */
+export interface SourceView {
+    name: string;
+    owner: string;
+    repo: string;
+    isPrivate: boolean;
+    defaultBranch: string;
+    branches: string[];
+}
+/** One row of `jules_list`. */
+export interface SessionRow {
+    id: string;
+    title: string;
+    state: string;
+    url: string;
+    source: string;
+    branch: string;
+    createTime: string;
+    updateTime: string;
+    pullRequests: string[];
+}
+/** The full picture `jules_status` returns. */
+export interface SessionDetail {
+    id: string;
+    title: string;
+    state: string;
+    url: string;
+    prompt: string;
+    source: string;
+    branch: string;
+    /**
+     * Whether the plan gate was in force, as `yes`, `no`, or `unknown`.
+     *
+     * The service treats this as a create-time *input* and does not echo it back,
+     * so a plain boolean here reported `false` for sessions that clearly
+     * honoured it. `unknown` is the honest answer when neither the session nor the
+     * log carries evidence either way.
+     */
+    requirePlanApproval: string;
+    /** Whether a PR is opened automatically, on the same yes/no/unknown terms. */
+    autoCreatePr: string;
+    archived: boolean;
+    createTime: string;
+    updateTime: string;
+    planId: string;
+    planSteps: string[];
+    /** A generated plan with no approval after it, which is what blocks the session. */
+    planPending: boolean;
+    planApproved: boolean;
+    pullRequests: string[];
+    generatedFiles: GeneratedFileView[];
+    /** The most recent shell command the agent ran, for diagnosing a stall. */
+    latestCommand: string;
+    /**
+     * True only when the call performing the projection had just approved a plan
+     * and then observed its `planApproved` event. False on every other call,
+     * including one that approved but could not confirm in time — the service is
+     * eventually consistent about its own actions, so this is the answer to "did
+     * my approval land", which the state field cannot give.
+     */
+    approvalConfirmed: boolean;
+    /** False only when a log read was attempted and failed, making its derived fields unknown. */
+    logRead: boolean;
+    /** The most recent message the agent sent, which is where a question or a blocker appears. */
+    lastMessage: string;
+    lastProgress: string;
+    /**
+     * Milliseconds since this same observation was last returned, or 0 when it is
+     * new. Non-zero means the caller is looking at a session that has not moved,
+     * which the renderer turns into a nudge to stop polling.
+     */
+    unchangedForMs: number;
+}
+/** Per-call facts a projection cannot derive from the session and its log. */
+export interface DetailOptions {
+    /** Milliseconds since this same observation was last returned; 0 when new. */
+    unchangedForMs?: number;
+    /** Whether this call approved a plan and then observed the approval. */
+    approvalConfirmed?: boolean;
+    /**
+     * Set false only when a read was attempted and failed. It then means every
+     * log-derived field below is *unknown*, not empty — a distinction that matters
+     * because "no plan pending" and "we could not look" call for opposite actions.
+     * Omitting it says nothing failed, which is also true of a projection that
+     * never looked.
+     */
+    logRead?: boolean;
+}
+/** One entry of `SessionDetail.generatedFiles`. */
+export interface GeneratedFileView {
+    path: string;
+    changeType: string;
+    /** Length of the file content the service reported. */
+    bytes: number;
+}
+/** One row of `jules_activities`. */
+export interface ActivityView {
+    id: string;
+    time: string;
+    originator: string;
+    kind: string;
+    summary: string;
+    artifacts: string[];
+}
+/** The canonical value of `jules_wait`. */
+export interface WaitResult {
+    id: string;
+    title: string;
+    state: string;
+    url: string;
+    settled: boolean;
+    timedOut: boolean;
+    needsAttention: boolean;
+    waitedMs: number;
+    polls: number;
+    planId: string;
+    planSteps: string[];
+    pullRequests: string[];
+    lastMessage: string;
+    lastProgress: string;
+}
+/** The canonical value of `jules_patch`. */
+export interface PatchResult {
+    id: string;
+    found: boolean;
+    /** The requested slice of the unified diff. */
+    patch: string;
+    /** Size of the whole diff, not of the slice. */
+    bytes: number;
+    /** Whether more of the diff remains after this slice. */
+    truncated: boolean;
+    /** Byte offset this slice started at. */
+    offset: number;
+    /** Offset to pass to continue reading, or 0 when this slice is the last. */
+    nextOffset: number;
+    /** Every path the whole diff touches, so a large patch is still reviewable at a glance. */
+    files: string[];
+    baseCommitId: string;
+    suggestedCommitMessage: string;
+    source: string;
+}
+/**
+ * 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 declare function activitySummary(activity: Activity): string;
+/**
+ * Project one session into a list row.
+ * @param session - the wire session.
+ * @returns the row value.
+ */
+export declare function sessionRow(session: Session): SessionRow;
+/**
+ * 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 declare function sessionDetail(session: Session, activities?: readonly Activity[], options?: DetailOptions): SessionDetail;
+/**
+ * Project one source into a row.
+ * @param source - the wire source.
+ * @returns the row value.
+ */
+export declare function sourceRow(source: Source): SourceView;
+/**
+ * Project one activity into a row.
+ * @param activity - the wire activity.
+ * @returns the row value.
+ */
+export declare function activityRow(activity: Activity): ActivityView;
+/**
+ * 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 declare function latestPatch(activities: readonly Activity[]): GitPatch | undefined;
+/**
+ * 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 declare function patchFiles(unidiff: string): string[];
+/**
+ * Render the source list.
+ * @param sources - projected rows.
+ * @returns the model-facing text.
+ */
+export declare function renderSources(sources: readonly SourceView[]): string;
+/**
+ * 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 declare function renderSessionRows(rows: readonly SessionRow[], nextPageToken: string): string;
+/**
+ * Render one session in full.
+ * @param detail - the projected detail.
+ * @returns the model-facing text.
+ */
+export declare function renderSessionDetail(detail: SessionDetail): string;
+/**
+ * Render an activity page.
+ * @param rows - projected rows.
+ * @param nextPageToken - continuation token, when the page was truncated.
+ * @returns the model-facing text.
+ */
+export declare function renderActivities(rows: readonly ActivityView[], nextPageToken: string): string;
+/**
+ * Render a wait result.
+ * @param result - the canonical wait value.
+ * @returns the model-facing text.
+ */
+export declare function renderWait(result: WaitResult): string;
+/**
+ * Render the newest patch, or explain why there is none.
+ * @param result - the canonical patch value.
+ * @returns the model-facing text.
+ */
+export declare function renderPatch(result: PatchResult): string;