@agntn/harnesses 0.2.1 → 0.3.0

package/dist/_chunks/prompt-sync.d.mts

@@ -9,6 +9,17 @@ export interface PathCandidate {
   platforms?: Platform[];
   note?: string;
 }
+/** The path lists of a harness descriptor, as named in {@link ResolvedPaths}. */
+export type PathCategory = "config" | "sessions" | "instructions" | "skills" | "commands" | "promptTemplates" | "hooks" | "temp";
+/**
+ * An environment variable the harness reads to move one of its roots. `path`
+ * is the default root, used while the variable is unset or empty.
+ */
+export interface EnvOverride extends PathCandidate {
+  variable: string;
+  /** Categories with entries under this root, which move with it. */
+  relocates: PathCategory[];
+}
 /** One stable user-scope destination used by prompt template synchronization. */
 export interface PromptTemplateSyncTarget extends PathCandidate {
   scope: "user";
@@ -49,6 +60,12 @@ export interface HarnessInvocation {
   readOnlyMinVersion?: string;
   /** Arguments appended when a model is selected; every "{model}" is replaced. */
   modelArgs?: string[];
+  /**
+   * Arguments appended to a plain text run so a CLI that holds its answer until
+   * the end reports it as events instead; `invoke` folds them back into that text,
+   * so a stopped run keeps what the model had already written.
+   */
+  streamArgs?: string[];
   level: EvidenceLevel;
   note?: string;
 }
@@ -65,7 +82,10 @@ export interface HarnessInvocationModes {
 export interface HarnessModelListing {
   /** Arguments used when no search filter is supplied. */
   args: string[];
-  /** Optional argument template for a search filter; every "{search}" is replaced. */
+  /**
+   * Optional argument template for a native search filter; every "{search}" is replaced.
+   * Without it, a search runs `args` and keeps the ids containing the filter, ignoring case.
+   */
   searchArgs?: string[];
   level: EvidenceLevel;
   note?: string;
@@ -74,10 +94,13 @@ export interface HarnessModelListing {
 export interface AvailableModel {
   provider: string;
   id: string;
-  contextWindow: number;
-  maxOutputTokens: number;
-  thinking: boolean;
-  images: boolean;
+  /** Absent when the native listing prints only ids, like Grok's. */
+  contextWindow?: number;
+  maxOutputTokens?: number;
+  thinking?: boolean;
+  images?: boolean;
+  /** Set on the model the harness picks when no model is given, when the listing marks one. */
+  default?: boolean;
 }
 /** Options for querying the models available to one harness. */
 export interface ListModelsOptions {
@@ -96,7 +119,7 @@ export interface InvokeOptions {
   model?: string;
   /** Enable the spawned harness's tools; defaults to advisor without tools mode. */
   tools?: boolean;
-  /** Require native enforcement of read-only tool access. Implies `tools: true`. */
+  /** Require native enforcement of read-only tool access. Implies `tools: true` when `tools` is omitted; `tools: false` rejects the run. */
   readOnly?: boolean;
   /** Milliseconds before cleanup starts. Unset or 0 disables the deadline. */
   timeoutMs?: number;
@@ -115,6 +138,8 @@ export interface InvokeResult {
   timedOut: boolean;
   /** True when caller cancellation wins over the deadline or completion. */
   aborted: boolean;
+  /** Milliseconds without output on either stream before a deadline or cancellation stopped the process. */
+  idleMs?: number;
 }
 /** Result of one native model-listing command. */
 export interface ListModelsResult extends InvokeResult {
@@ -160,6 +185,8 @@ export interface ResolveOptions {
   homeDir?: string;
   projectRoot?: string;
   platform?: Platform;
+  /** Replaces `os.tmpdir()` as the value of `${TMPDIR}`. */
+  tempDir?: string;
 }
 export interface ResolvedPaths {
   config: PathCandidate[];
@@ -170,6 +197,8 @@ export interface ResolvedPaths {
   promptTemplates: PathCandidate[];
   promptTemplateSyncTarget: PromptTemplateSyncTarget | null;
   hooks: PathCandidate[];
+  /** Temp roots, moved by a set `temp` override from {@link EnvOverride}. */
+  temp: PathCandidate[];
 }
 type InvocationOptions = Readonly<{
   model?: string;
@@ -192,6 +221,10 @@ export declare abstract class Harness {
   /** Stable user-scope destination used by prompt template synchronization. */
   readonly promptTemplateSyncTarget: PromptTemplateSyncTarget | null;
   abstract readonly hooks: PathCandidate[];
+  /** Where the harness keeps its temp files; empty when not verified. */
+  readonly temp: PathCandidate[];
+  /** Environment variables that move a root of this harness; empty when none is verified. */
+  readonly envOverrides: EnvOverride[];
   abstract readonly capabilities: HarnessCapabilities;
   abstract readonly detection: HarnessDetection;
   /** Non-interactive invocation recipe; null when the harness has no headless mode. */
@@ -246,6 +279,15 @@ export declare abstract class Harness {
    * @returns {Promise<InvokeResult>} The completed process result.
    */
   invoke(prompt: string, options?: InvokeOptions): Promise<InvokeResult>;
+  /**
+   * Turns the events a `streamArgs` run printed back into the text the plain
+   * run would have printed.
+   *
+   * @param _stdout - Event output as captured, possibly cut short.
+   * @param _complete - False when a deadline or cancellation stopped the run.
+   * @returns {string} The answer text, or what the model had written so far.
+   */
+  protected foldStreamOutput(_stdout: string, _complete: boolean): string;
   /**
    * Explains why the installed CLI cannot run a read-only recipe that carries a
    * version floor, or returns null when no floor applies or the installed
@@ -258,7 +300,8 @@ export declare abstract class Harness {
   /**
    * Expands the native model-listing recipe without spawning anything.
    *
-   * @param search - Optional native model search filter.
+   * @param search - Optional model search filter; without native `searchArgs` it is applied
+   *   to the parsed output instead, so the command is the unfiltered one.
    * @returns {{ command: string, args: string[] } | null} The command, or null when unsupported.
    */
   buildModelListInvocation(search?: string): {
@@ -273,6 +316,14 @@ export declare abstract class Harness {
    * @returns {Promise<ListModelsResult>} The normalized command and model result.
    */
   listModels(options?: ListModelsOptions): Promise<ListModelsResult>;
+  /**
+   * The value `model` takes for one listed model: `provider/id` unless the
+   * harness overrides it.
+   *
+   * @param model - A model returned by {@link listModels}.
+   * @returns {string} The selector this harness's `modelArgs` accept.
+   */
+  modelSelector(model: Readonly<AvailableModel>): string;
   /**
    * Converts a successful native model-listing response to the shared shape.
    *
@@ -290,6 +341,14 @@ export declare abstract class Harness {
    */
   resolveCandidates<T extends PathCandidate>(entries: readonly T[], options?: ResolveOptions): T[];
   resolve(options?: ResolveOptions): ResolvedPaths;
+  /**
+   * Temp roots for the platform. A `temp` override set in the environment
+   * replaces its default root, the same move the harness makes itself.
+   *
+   * @param options - Platform and path-resolution overrides.
+   * @returns {PathCandidate[]} Resolved temp roots.
+   */
+  private resolveTemp;
 }
 export type HarnessConstructor = new () => Harness;
 /** One resolved config file together with the servers it declares. */
@@ -471,6 +530,9 @@ export interface PromptSyncTargetResult {
   readonly id: string;
   readonly path?: string;
   readonly format?: PromptTemplateSyncTarget["format"];
+  /** Outcome for a Markdown destination, which is one link to the whole source directory. */
+  readonly action?: PromptSyncAction;
+  /** Backup path, skip reason, or a check-mode note. */
   readonly detail?: string;
   readonly templates: readonly PromptTemplateTargetResult[];
 }
@@ -483,8 +545,10 @@ export interface PromptSyncReport {
 }
 /**
  * Synchronizes canonical Markdown prompt templates into each harness's stable
- * user-scope destination. Markdown harnesses receive symlinks; Gemini receives
- * generated TOML commands. In check mode nothing is written.
+ * user-scope destination. A Markdown harness's destination becomes one symlink
+ * to the source directory; Gemini's directory holds only TOML commands
+ * generated from it. Anything else found there is backed up first. In check
+ * mode nothing is written.
  *
  * @param harnesses - Harnesses to inspect or update.
  * @param check - Report intended changes without writing them.

package/dist/_chunks/prompt-sync.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-sync.d.mts","names":[],"sources":["../../src/types.ts","../../src/harness.ts","../../src/mcp-servers.ts","../../src/agents-sync.ts","../../src/prompt-sync.ts"],"mappings":"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"}
+{"version":3,"file":"prompt-sync.d.mts","names":[],"sources":["../../src/types.ts","../../src/harness.ts","../../src/mcp-servers.ts","../../src/agents-sync.ts","../../src/prompt-sync.ts"],"mappings":"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"}