@deepseek-ai/dsh-experimental-forge-session 0.0.0-stage → 0.2.2-alpha.3

package/lib/types/commands.d.ts

@@ -0,0 +1,63 @@
+/** Recognition of shell commands and output that bind change requests to a Session. */
+import type { CommandEvidence } from './types.ts';
+/** One branch a `git push` output reported as updated. */
+export interface PushedRef {
+    /** Remote as `git push` printed it after `To`. */
+    readonly remote: string;
+    /** Branch name on the remote. */
+    readonly branch: string;
+}
+/**
+ * Read the command string of a `bash` or `pwsh` tool call.
+ * @param argumentsJson - raw tool-call arguments as the model produced them.
+ * @returns the command, or undefined when the arguments are not JSON or carry no string `command`.
+ */
+export declare function commandOf(argumentsJson: string): string | undefined;
+/**
+ * Classify the binding evidence a command and its output can carry.
+ * `gh pr create` (or its alias `gh pr new`) prints the change request URL;
+ * `gh pr view`, `gh pr edit`, and `gh pr checkout` act on one change request,
+ * which a URL or a number with an explicit repository and host can name;
+ * their output can also print its URL. `git push`,
+ * with or without leading `-C`, `-c`, and long options, prints the updated
+ * refs. When a command does both, the URLs a result prints bind as created.
+ * The match is textual, so quoted mentions also classify; the result parsers
+ * then find no evidence in their output.
+ * @param command - shell command text.
+ * @returns the evidence, or undefined when the command has none of these forms.
+ */
+export declare function commandEvidence(command: string): CommandEvidence | undefined;
+/**
+ * Find GitHub pull request URLs in command output.
+ * @param text - rendered shell result.
+ * @returns distinct URLs in order of first appearance.
+ */
+export declare function changeRequestUrls(text: string): string[];
+/**
+ * Find the URLs that `gh pr view`, `gh pr edit`, or `gh pr checkout` output
+ * prints for the change request it acts on: gh's `url:` field or a URL alone
+ * on a line before the `--` line that starts a description, and JSON `url`
+ * members. Links in a description or in other fields name other pages.
+ * @param text - rendered shell result.
+ * @returns distinct URLs in order of first appearance.
+ */
+export declare function ownChangeRequestUrls(text: string): string[];
+/**
+ * Find branches that `git push` output reports as created, updated, forced,
+ * or already up to date. Each ref line belongs to the nearest preceding
+ * `To <remote>` line. Rejected and deleted refs, new tags, and explicit refs
+ * outside `refs/heads/` are excluded. Unqualified tag updates cannot be
+ * distinguished from branch updates and are included.
+ * @param text - rendered shell result, stdout and stderr.
+ * @returns distinct pushed branches in order of first appearance.
+ */
+export declare function pushedBranches(text: string): PushedRef[];
+/**
+ * Compare two change request URLs ignoring scheme, letter case, query,
+ * fragment, and trailing slashes.
+ * @param left - one URL.
+ * @param right - the other URL.
+ * @returns whether both name the same web page.
+ */
+export declare function sameChangeRequestUrl(left: string, right: string): boolean;
+//# sourceMappingURL=commands.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,91 @@
+/** Binds change requests to the Session that created, pushed, or tracked them, and watches the bound ones. */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { Config, SessionChangeRequest, SessionChangeRequestsListener } from './types.ts';
+export type * from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        forgeSession: ForgeSessionService;
+    }
+}
+/**
+ * Session-scoped change request bindings. The `forgeChangeRequests`
+ * projection derives them from `gh pr create`, `gh pr view`, `gh pr edit`,
+ * `gh pr checkout`, and `git push` results and from
+ * `plugin:forge-session/binding` records. After each push result, and when a
+ * caller reports the branch a Session works on, the service looks up open
+ * change requests whose head is that branch and records the unbound ones as
+ * discovered. Watching a Session polls its visible change requests through
+ * `ctx.forge`.
+ */
+export declare class ForgeSessionService extends Service {
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly home;
+    private readonly discoveryTimeoutMs;
+    private readonly watches;
+    private readonly discoveries;
+    private readonly sessionLifetimes;
+    private readonly lifetime;
+    private projection;
+    constructor(ctx: Context, config: Config);
+    /**
+     * List the change requests bound to a Session and not dismissed.
+     * @param session - Session whose bindings are read.
+     * @returns visible bindings in first-recorded order, each with its latest polling result.
+     */
+    changeRequests(session: Session): SessionChangeRequest[];
+    /**
+     * Bind a change request to a Session by URL, or restore a dismissed binding.
+     * Appends a `track` record with the provider's canonical URL unless the
+     * change request is already visible.
+     * @param session - Session that receives the binding.
+     * @param url - web URL of the change request.
+     * @throws when no registered provider recognizes the URL.
+     */
+    track(session: Session, url: string): void;
+    /**
+     * Look up open change requests whose head is a branch the Session works on,
+     * and record the unbound ones as discovered, as after a push of that branch.
+     * A remote that no provider recognizes changes nothing; a failed lookup is
+     * logged and changes nothing.
+     * @param session - Session that receives the bindings.
+     * @param remote - URL of the remote that holds the branch.
+     * @param branch - branch name on that remote.
+     * @returns resolves once the lookup has recorded its bindings or failed.
+     */
+    discoverBranch(session: Session, remote: string, branch: string): Promise<void>;
+    /**
+     * Hide a visible binding. Appends a `dismiss` record; a URL that is not
+     * visibly bound leaves the log unchanged. Discovery never restores a
+     * dismissed binding; `track` does.
+     * @param session - Session that owns the binding.
+     * @param url - web URL of the change request.
+     */
+    dismiss(session: Session, url: string): void;
+    /**
+     * Watch a Session's visible change requests as an effect on the calling
+     * fiber. Every visible change request that a provider recognizes is polled
+     * through `ctx.forge` while the Session has a watcher. Listeners receive the
+     * complete list after each later binding or provider change, or polling result; read the
+     * current list with {@link changeRequests}. Listeners must not throw; a
+     * thrown error is logged and skipped.
+     * @param session - Session to watch.
+     * @param listener - receives the complete visible list.
+     * @returns the disposer that stops this watch.
+     */
+    watch(session: Session, listener: SessionChangeRequestsListener): () => void;
+    protected [Service.init](): Promise<void>;
+    private state;
+    private entries;
+    /** Discover change requests for this result's pushes and refresh watchers after binding changes. */
+    private react;
+    /** Poll exactly the visible change requests that a provider recognizes. */
+    private sync;
+    private notify;
+    private discover;
+    private lookup;
+}
+export default ForgeSessionService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/projection.d.ts

@@ -0,0 +1,33 @@
+/** Projection that folds shell results and binding records into one Session's change request bindings, and shows clients the bindings. */
+import { z } from 'zod';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { BindingState, ForgeChangeRequestsState } from './types.ts';
+/** Plugin record type of binding actions. */
+export declare const BINDING_RECORD = "plugin:forge-session/binding";
+/**
+ * The `forgeChangeRequests` unit. A `bash` or `pwsh` call whose command is
+ * `gh pr create`, `gh pr view`, `gh pr edit`, `gh pr checkout`, or
+ * `git push` stays pending until its first result. A successful result binds
+ * every pull request URL a `gh pr create` result prints; for the other `gh pr`
+ * commands it binds the URL the command names and the URL the output prints
+ * for its own change request; and it records the branches it reports as
+ * pushed. Failed tool executions bind nothing; a nonzero exit status does not
+ * matter, because the URL or ref line is the evidence. `turn/end` drops calls
+ * that never received a result. Binding records bind, restore, and hide URLs.
+ * Clients, including the Session summary, see the bindings; the array keeps
+ * its reference while only pending calls and pushes change.
+ */
+export declare const forgeChangeRequestsProjection: {
+    key: "forgeChangeRequests";
+    stateVersion: number;
+    stateSchema: z.ZodType<ForgeChangeRequestsState, unknown, z.core.$ZodTypeInternals<ForgeChangeRequestsState, unknown>>;
+    init: () => ForgeChangeRequestsState;
+    apply: typeof apply;
+    wire: {
+        viewSchema: z.ZodType<readonly BindingState[], unknown, z.core.$ZodTypeInternals<readonly BindingState[], unknown>>;
+        view: (state: NoInfer<ForgeChangeRequestsState>) => readonly BindingState[];
+    };
+};
+declare function apply(state: ForgeChangeRequestsState, event: SessionEvent): ForgeChangeRequestsState;
+export {};
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/reference-lookup.d.ts

@@ -0,0 +1,15 @@
+/** Resolve unqualified CLI references in the shell execution world and persist only confirmed URLs. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+/**
+ * Observe completed foreground Bash calls while tools and shell services exist.
+ * Queries use the same shell service, cwd, managed environment, and standing
+ * sandbox policy. Failed lookups leave bindings unchanged and log a warning.
+ * Cancellation leaves bindings unchanged; disposal aborts and awaits all queries.
+ * Replay performs no lookup.
+ * @param ctx - owning plugin context.
+ * @param timeoutMs - shell deadline for one read-only lookup.
+ * @param record - persists a confirmed URL without restoring dismissed bindings.
+ */
+export declare function observeReferences(ctx: Context, timeoutMs: number, record: (session: Session, url: string) => void): void;
+//# sourceMappingURL=reference-lookup.d.ts.map

package/lib/types/references.d.ts

@@ -0,0 +1,19 @@
+/** Literal GitHub CLI references, with shell quoting and command separators preserved. */
+/** One PR explicitly selected by a supported GitHub CLI invocation. */
+export interface GhReference {
+    /** Canonical URL when the command supplies its host, otherwise null. */
+    readonly url: string | null;
+    /** Read-only command for an unqualified repository in the first simple command, otherwise null. */
+    readonly lookup: string | null;
+}
+/**
+ * Read explicit URL selectors or numeric selectors with `--repo`/`-R`.
+ * Shell expansion, multiline scripts, substitutions, and unsupported options
+ * are excluded. Unqualified repositories can be resolved only for a single
+ * simple command, optionally piped to an output filter; compound commands
+ * may change the CLI environment. PowerShell callers may use only `url`.
+ * @param command - logged shell command text.
+ * @returns references in command order; no process or environment is read.
+ */
+export declare function ghReferences(command: string): GhReference[];
+//# sourceMappingURL=references.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,96 @@
+/** Session binding vocabulary, the binding plugin record, and the host-only projection state. */
+import type { ChangeRequestRef, ChangeRequestUpdate } from '@deepseek-ai/dsh-experimental-forge/types';
+import type { SessionSeq } from '@deepseek-ai/dsh-session/types';
+/**
+ * How a change request became bound to a Session: `created` when a
+ * `gh pr create` result printed its URL, `referenced` when a `gh pr view`,
+ * `gh pr edit`, or `gh pr checkout` call named it or its result printed its
+ * own URL, `discovered` when a lookup found it for a branch the Session pushed
+ * or works on, `tracked` when a caller bound it by URL.
+ */
+export type BindingOrigin = 'created' | 'referenced' | 'discovered' | 'tracked';
+/** Binding evidence that a shell command and its result can carry. */
+export interface CommandEvidence {
+    /** Origin of the change request URLs the result prints, or null when the command prints none of its own. */
+    readonly urls: 'created' | 'referenced' | null;
+    /** Whether the result can report pushed refs. */
+    readonly pushes: boolean;
+    /** Change request URLs explicitly selected by URL or by number, repository, and host. */
+    readonly named: readonly string[];
+}
+/** Payload of the `plugin:forge-session/binding` record. */
+export interface BindingRecord {
+    /**
+     * `track` binds or restores, `dismiss` hides, `discover` binds a branch lookup,
+     * and `reference` binds a CLI selector lookup without restoring dismissed entries.
+     */
+    readonly action: 'track' | 'dismiss' | 'discover' | 'reference';
+    /** Web URL of the change request. */
+    readonly url: string;
+}
+/** One shell call whose result the projection still awaits, with the evidence the call and its result carry. */
+export interface PendingCommand extends CommandEvidence {
+    /** Tool call id that pairs the call with its result. */
+    readonly callId: string;
+}
+/** One change request remembered by the projection, including hidden ones. */
+export interface BindingState {
+    /** Web URL as first recorded. */
+    readonly url: string;
+    /** How the change request became bound. */
+    readonly origin: BindingOrigin;
+    /** Whether a dismissal hides the binding. */
+    readonly dismissed: boolean;
+}
+/** One branch that a `git push` result reported as updated on a remote. */
+export interface PushedBranch {
+    /** Remote as `git push` printed it after `To`. */
+    readonly remote: string;
+    /** Branch name on the remote. */
+    readonly branch: string;
+    /** Sequence number of the latest `tool/result` event that reported this branch. */
+    readonly seq: SessionSeq;
+}
+/** Host-only projection state folded from shell results and binding records. */
+export interface ForgeChangeRequestsState {
+    /** Shell calls awaiting their result, in call order. */
+    readonly pending: readonly PendingCommand[];
+    /** Bound change requests in first-recorded order. */
+    readonly bindings: readonly BindingState[];
+    /** Pushed branches, one entry per remote and branch, ordered by latest push. */
+    readonly pushes: readonly PushedBranch[];
+}
+/** One change request bound to a Session and not dismissed, with its latest polling result. */
+export interface SessionChangeRequest {
+    /** Web URL as first recorded. */
+    readonly url: string;
+    /** How the change request became bound. */
+    readonly origin: BindingOrigin;
+    /** Parsed reference, or null when no registered provider serves the URL. */
+    readonly ref: ChangeRequestRef | null;
+    /** Latest polling result, or null before the first poll and without a provider. */
+    readonly update: ChangeRequestUpdate | null;
+}
+/**
+ * Receives the complete visible list after a binding or provider change, or a polling result.
+ * @param changeRequests - every visible binding of the watched Session, in first-recorded order.
+ */
+export type SessionChangeRequestsListener = (changeRequests: readonly SessionChangeRequest[]) => void;
+/** Deployment settings of `forgeSession`. */
+export interface Config {
+    /** Deadline in milliseconds for one change request lookup after a push. */
+    discoveryTimeoutMs?: number;
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface PluginRecordMap {
+        /** A caller or discovery action that binds, restores, or hides one change request. */
+        'plugin:forge-session/binding': BindingRecord;
+    }
+}
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionMap {
+        /** Every change request bound to the Session, hidden ones included, in binding order. */
+        forgeChangeRequests: readonly BindingState[];
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/locale/de.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Änderungsanfragen der Sitzung",
+    "description": "Verknüpfen Sie Änderungsanfragen mit der Sitzung, die sie erstellt, gepusht oder verfolgt hat, und überwachen Sie ihren Status."
+  }
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Session change requests",
+    "description": "Bind change requests to the Session that created, pushed, or tracked them, and watch their status."
+  }
+}

package/locale/es.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Solicitudes de cambio de la sesión",
+    "description": "Vincule las solicitudes de cambio a la sesión que las creó, envió o siguió, y supervise su estado."
+  }
+}

package/locale/fr.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Demandes de modification de la session",
+    "description": "Associez les demandes de modification à la session qui les a créées, poussées ou suivies, et surveillez leur état."
+  }
+}

package/locale/ja.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "セッションの変更リクエスト",
+    "description": "変更リクエストを、それを作成・プッシュ・追跡したセッションに関連付け、状態を監視します。"
+  }
+}

package/locale/pt.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Solicitações de alteração da sessão",
+    "description": "Vincule as solicitações de alteração à sessão que as criou, enviou ou acompanhou e monitore seu status."
+  }
+}

package/locale/ru.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Запросы на изменение сеанса",
+    "description": "Привяжите запросы на изменение к сеансу, который их создал, отправил или отслеживал, и следите за их статусом."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "会话变更请求",
+    "description": "把变更请求绑定到创建、推送或跟踪它们的会话，并监听其状态。"
+  }
+}

package/package.json

@@ -1,6 +1,88 @@
 {
   "name": "@deepseek-ai/dsh-experimental-forge-session",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Binds change requests to the Session that created, pushed, or tracked them",
+  "version": "0.2.2-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts"
+    },
+    "./locale/*.json": "./locale/*.json",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "locale/*.json",
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/experimental/forge-session"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-timeout": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-util-values": "0.2.2-alpha.3",
+    "@deepseek-ai/schemastery": "~3.18.6-alpha.2",
+    "shell-quote": "^1.12.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2",
+    "@deepseek-ai/dsh-experimental-forge": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-shell": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-shell-env": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.2-alpha.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2",
+    "@deepseek-ai/cordis-plugin-include": "~1.0.11-alpha.2",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.7-alpha.2",
+    "@deepseek-ai/dsh-agent": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-agent-loop": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-bash-local": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-experimental-forge": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-experimental-forge-github": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-fs-local": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-shell-env": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-subprocess-local": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tool-bash": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tool-executor-native": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-working-directory": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-shell": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.2-alpha.3"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-shell": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-shell-env": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-sandbox-policy": {
+      "optional": true
+    }
+  }
 }