@zhangj1164/dsh-github-issue 0.2.0 → 0.4.0

package/lib/index.d.ts

@@ -1,8 +1,9 @@
-import { GithubIssueAnalysisWindow, GithubIssueFailureGroupInput, GithubIssueFailureRoute, GithubIssueGenerateReportRequest, GithubIssueGenerateReportResult, GithubIssueOptimizeRequest, GithubIssueOptimizeResult, GithubIssuePrefillRequest, GithubIssuePrefillResult, GithubIssueReport } from "./types.js";
+import { GithubIssueAnalysisWindow, GithubIssueCreateRequest, GithubIssueCreateResult, GithubIssueCreated, GithubIssueDispatchRequest, GithubIssueDispatchResult, GithubIssueDispatched, GithubIssueFailure, GithubIssueFailureCode, GithubIssueFailureGroupInput, GithubIssueFailureRoute, GithubIssueGenerateReportRequest, GithubIssueGenerateReportResult, GithubIssueIntakeFailure, GithubIssueIntakeRequest, GithubIssueIntakeResult, GithubIssueIntakeValue, GithubIssueListRequest, GithubIssueListResult, GithubIssueOptimizeRequest, GithubIssueOptimizeResult, GithubIssuePrefillRequest, GithubIssuePrefillResult, GithubIssueReport, GithubIssueTask } from "./types.js";
+import { Context, Service } from "@deepseek-ai/cordis";
 import s from "@deepseek-ai/schemastery";
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { GenerateOptions, StreamChunk } from "@deepseek-ai/dsh-llm";
-import { Context } from "@deepseek-ai/cordis";
+import { Volatile } from "@deepseek-ai/cosmokit";
 //#region src/llm-text.d.ts
 /**
  * Minimal shape of the DSH `llm` service this helper needs. Declared
@@ -40,14 +41,22 @@ type LlmTextResult = {
 };
 //#endregion
 //#region src/index.d.ts
-/** Deployment configuration for the GitHub-issue service. */
+/**
+ * Deployment configuration for the GitHub-issue service.
+ *
+ * The fields a settings surface may rewrite (`repoUrl`, `claimLabel`,
+ * `maxIssuesPerRun`, and the five autopilot fields) are {@link Volatile}: the
+ * Loader resolves each into a ref it updates in place, so an accepted settings
+ * write reaches the running service without a restart. The remaining fields
+ * are deployment-only and stay in `cordis.yml`.
+ */
 interface Config {
   /**
    * The GitHub repository URL for issue prefill (e.g.
    * `https://github.com/owner/repo`). Used as the default when a request omits
    * `repoUrl`. The deployment sets this to the real project repository.
    */
-  readonly repoUrl: string;
+  readonly repoUrl: Volatile<string>;
   /**
    * Longest pre-filled issue URL to produce, counted in characters.
    *
@@ -73,6 +82,76 @@ interface Config {
    * `agentDefaultModel` selection.
    */
   readonly model?: string;
+  /**
+   * Environment variable that carries the GitHub token. Read only when
+   * {@link Config.token} is unset, and only when no token command is configured
+   * or the command produced nothing.
+   */
+  readonly tokenEnv: string;
+  /**
+   * Explicit GitHub token. A deployment that manages secrets itself sets this;
+   * a token stored in the environment or produced by {@link Config.tokenCommand}
+   * is read when this field is absent.
+   */
+  readonly token?: string;
+  /**
+   * Command whose standard output is a GitHub token, run only when neither
+   * {@link Config.token} nor {@link Config.tokenEnv} supplies one. The default
+   * reads the credential the `gh` CLI already stores, so a machine that is
+   * logged in to GitHub needs no extra secret; set it to an empty string to
+   * disable the lookup.
+   */
+  readonly tokenCommand: string;
+  /** Deadline for {@link Config.tokenCommand}, in milliseconds. */
+  readonly tokenCommandTimeoutMs: number;
+  /**
+   * GitHub REST origin. `https://api.github.com` serves github.com; an
+   * Enterprise deployment sets its own `https://host/api/v3`.
+   */
+  readonly apiBaseUrl: string;
+  /** Deadline for one GitHub REST request, in milliseconds. */
+  readonly requestTimeoutMs: number;
+  /**
+   * Label that marks an issue claimable by the intake loop. The repository's
+   * triage vocabulary owns the value; this field only names which label counts.
+   */
+  readonly claimLabel: Volatile<string>;
+  /** Largest number of issues one intake pass may dispatch. */
+  readonly maxIssuesPerRun: Volatile<number>;
+  /**
+   * Whether the host checks for claimable issues on its first startup of the
+   * day. Off by default: opening a Session without being asked is a deployment
+   * decision, never a surprise a plugin installs on its own.
+   */
+  readonly autopilotEnabled: Volatile<boolean>;
+  /**
+   * Working directory the dispatched Sessions own. Empty follows the host's
+   * default directory, which is the deployment's current working directory.
+   */
+  readonly autopilotCwd: Volatile<string>;
+  /** Agent preset the dispatched Sessions run; empty follows the deployment default. */
+  readonly autopilotPreset: Volatile<string>;
+  /**
+   * IANA zone "today" is measured in. Empty follows the host's own zone, so a
+   * user's local midnight is what starts a new day.
+   */
+  readonly autopilotTimeZone: Volatile<string>;
+  /**
+   * Prompt template handed to every dispatched Session. Placeholders are
+   * documented on `renderDispatchPrompt`; the default states the issue
+   * location and points at the repository workflow.
+   */
+  readonly autopilotPrompt: Volatile<string>;
+  /**
+   * Seconds between registering a dispatch's automation task and its delivery.
+   *
+   * The Schedule service refuses a non-positive delay, so this is at least one
+   * second. It stays a deployment-level value instead of a constant because a
+   * deployment may want the task to sit visibly on the board before it fires,
+   * and it stays out of the settings surface: it times a dispatch, it does not
+   * describe one.
+   */
+  readonly dispatchTaskDelaySeconds: number;
 }
 /** Schemastery configuration for the GitHub-issue service. */
 declare const Config: s<Config>;
@@ -83,22 +162,62 @@ declare module '@deepseek-ai/cordis' {
 }
 /**
  * GitHub-issue generation and optimization service over the configured model.
+ *
+ * Beyond the model-backed report methods, the service owns the issue intake
+ * loop: it files an optimized report through the GitHub REST API, lists the
+ * issues that carry the claim label, and hands one of them to a fresh Session.
  */
 declare class GithubIssueService extends TypertRemoteService {
   static inject: string[];
   static Config: s<Config>;
-  private readonly repoUrl;
   private readonly maxPrefillUrlLength;
   private readonly prefillTruncationNote;
   /** Configured provider route, or `undefined` to follow `agentDefaultModel`. */
   private readonly provider?;
   /** Configured model id, or `undefined` to follow `agentDefaultModel`. */
   private readonly model?;
+  private readonly tokenEnv;
+  private readonly token?;
+  private readonly tokenCommand;
+  private readonly tokenCommandTimeoutMs;
+  private readonly apiBaseUrl;
+  private readonly requestTimeoutMs;
+  /** The persisted state, or the empty state when this deployment has no storage. */
+  private intakeState;
+  /** The durable table, absent when this deployment mounts no storage domain. */
+  private intakeTable?;
+  /** Whether the state is durable; the startup check refuses to run without it. */
+  private intakePersistent;
+  /** The resolved token, cached so a token command runs at most once. */
+  private resolvedToken?;
+  /** Whether token resolution finished; a missing credential is a result, not a retry. */
+  private tokenResolved;
+  /** The last invalid time zone already reported, so a warning is not repeated per call. */
+  private warnedTimeZone;
   /**
    * @param ctx - Host context carrying the llm service.
    * @param config - Validated deployment configuration.
    */
   constructor(ctx: Context, config: Config);
+  /**
+   * The IANA zone the intake day is measured in.
+   *
+   * Read per call: a settings surface can rewrite it while the service runs. An
+   * invalid zone must not break the startup check or a dispatch, so it falls
+   * back to the host zone and is reported once per changed value.
+   * @returns the configured zone, or an empty string for the host zone.
+   */
+  private intakeTimeZone;
+  /**
+   * Open the durable intake state and, when enabled, run the first-startup
+   * check.
+   *
+   * The check is deliberately not awaited: opening a Session is useful work
+   * but not a prerequisite for the service, and a slow or unreachable GitHub
+   * must not hold up the host's boot. A failure is logged and retried on the
+   * next startup, because the day key is only committed after a completed pass.
+   */
+  protected [Service.init](): Promise<void>;
   /**
    * Resolve the model route for one model call.
    *
@@ -140,6 +259,130 @@ declare class GithubIssueService extends TypertRemoteService {
    * @returns the structured report or an LLM failure.
    */
   optimizeIssue(request: GithubIssueOptimizeRequest): Promise<GithubIssueOptimizeResult>;
+  /**
+   * File one issue in the configured repository.
+   *
+   * The body is filed without its leading title heading: the optimizer repeats
+   * the title there so one text can drive both the pre-filled URL form and a
+   * direct filing, and GitHub takes the title as its own field.
+   *
+   * @param request - repository override and the report to file.
+   * @returns the created issue, or a stable failure.
+   */
+  createIssue(request: GithubIssueCreateRequest): Promise<GithubIssueCreateResult>;
+  /**
+   * List the open issues that carry the claim label.
+   * @param request - repository, label, and count overrides.
+   * @returns the claimable issues, or a stable failure.
+   */
+  listClaimableIssues(request?: GithubIssueListRequest): Promise<GithubIssueListResult>;
+  /**
+   * Hand one issue to a fresh Session.
+   * @param request - the issue and optional Session placement.
+   * @returns the created Session, or a stable failure.
+   */
+  dispatchIssue(request: GithubIssueDispatchRequest): Promise<GithubIssueDispatchResult>;
+  /**
+   * Run one intake pass: list the claimable issues, skip the ones an earlier
+   * pass already dispatched, and hand the rest to a fresh Session.
+   *
+   * The local day is committed only after the listing succeeded, so a pass that
+   * could not reach GitHub is retried on the next startup instead of being
+   * remembered as done. An issue that was already dispatched is never
+   * dispatched again, even on a later day: its Session exists, and a second one
+   * would duplicate the work.
+   *
+   * @param request - repository, label, count, and Session placement overrides.
+   * @returns what the pass read and did.
+   */
+  runIntake(request?: GithubIssueIntakeRequest): Promise<GithubIssueIntakeResult>;
+  /**
+   * Create one Session, register its automation task, and name the Session.
+   *
+   * A dispatch is two steps. The Session is created through the controller, so
+   * the deployment's preset and workspace policy apply. The work is then handed
+   * over as a one-shot automation task on the Schedule service: the task shows
+   * up in the Web's automation board, and the service delivers its prompt into
+   * that Session when the task becomes due. A task is always bound to an
+   * existing Session — the board never opens one by itself — so the Session has
+   * to exist first, and registering the task is what makes the dispatch visible
+   * beyond the sidebar.
+   *
+   * A deployment that mounts no Schedule service (a non-Web composition) falls
+   * back to admitting the prompt directly, the same durable admission the Web
+   * prompt uses. Both paths fail the dispatch when the host refuses, so a
+   * refusal never leaves the day marked as checked.
+   *
+   * @param request - the issue and optional Session placement.
+   * @returns the created Session, or a stable failure.
+   */
+  private dispatch;
+  /**
+   * Name a dispatched Session so the user can recognise it in the sidebar.
+   *
+   * A title is presentation, not part of the dispatch contract: a deployment
+   * that mounts no title service still gets a working Session, so a failure
+   * here is logged and never fails the dispatch.
+   *
+   * @param controller - the Session controller.
+   * @param sessionId - the Session to name.
+   * @param title - the proposed title.
+   */
+  private renameSession;
+  /**
+   * Run the first-startup check once per local day.
+   *
+   * The day is read from durable state, so a restart later the same day does
+   * nothing; the check is skipped until the local calendar moves on.
+   */
+  private startupIntake;
+  /**
+   * Open the durable intake state when this deployment mounts storage.
+   *
+   * Storage is optional so the service still installs on its own bundle; the
+   * startup check then stays off rather than running without a memory of what
+   * it already dispatched.
+   */
+  private openIntakeState;
+  /**
+   * Commit one completed pass to durable state.
+   *
+   * The in-memory state is updated first so the next pass in this process sees
+   * the dispatch even when the durable write fails; the warning then names the
+   * consequence instead of pretending the write succeeded.
+   *
+   * @param day - local day the pass completed.
+   * @param dispatched - issues handed to a Session in this pass.
+   */
+  private commitIntakeState;
+  /**
+   * Build one GitHub client for a call.
+   * @param repoUrl - repository override, or the configured repository.
+   * @returns the client, carrying the resolved credential.
+   */
+  private createClient;
+  /**
+   * Resolve the GitHub credential once.
+   *
+   * The order is explicit config, then the configured environment variable,
+   * then the configured command. The command runs at most once per process so
+   * a keyring-backed credential is not fetched on every request, and its output
+   * is never logged.
+   *
+   * @returns the token, or undefined when the deployment has none.
+   */
+  private resolveToken;
+  /**
+   * The telemetry feature anchor for one intake action.
+   * @param action - the method the event belongs to.
+   * @returns the stable feature-code reference.
+   */
+  private featureCode;
+  /**
+   * Log one non-fatal intake problem.
+   * @param message - what went wrong and what it costs.
+   */
+  private warn;
   /**
    * Report one model failure and return the business failure.
    *
@@ -195,4 +438,4 @@ declare class GithubIssueService extends TypertRemoteService {
   private trackError;
 }
 //#endregion
-export { Config, type GithubIssueAnalysisWindow, type GithubIssueFailureGroupInput, type GithubIssueFailureRoute, type GithubIssueGenerateReportRequest, type GithubIssueGenerateReportResult, type GithubIssueOptimizeRequest, type GithubIssueOptimizeResult, type GithubIssuePrefillRequest, type GithubIssuePrefillResult, type GithubIssueReport, GithubIssueService, GithubIssueService as default, type LlmRoute, type LlmTextFailure, type LlmTextResult, type LlmTextSource };
+export { Config, type GithubIssueAnalysisWindow, type GithubIssueCreateRequest, type GithubIssueCreateResult, type GithubIssueCreated, type GithubIssueDispatchRequest, type GithubIssueDispatchResult, type GithubIssueDispatched, type GithubIssueFailure, type GithubIssueFailureCode, type GithubIssueFailureGroupInput, type GithubIssueFailureRoute, type GithubIssueGenerateReportRequest, type GithubIssueGenerateReportResult, type GithubIssueIntakeFailure, type GithubIssueIntakeRequest, type GithubIssueIntakeResult, type GithubIssueIntakeValue, type GithubIssueListRequest, type GithubIssueListResult, type GithubIssueOptimizeRequest, type GithubIssueOptimizeResult, type GithubIssuePrefillRequest, type GithubIssuePrefillResult, type GithubIssueReport, GithubIssueService, GithubIssueService as default, type GithubIssueTask, type LlmRoute, type LlmTextFailure, type LlmTextResult, type LlmTextSource };