@agentworkforce/workload-router 0.1.2 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +115 -1
- package/dist/generated/personas.d.ts +1 -1
- package/dist/generated/personas.js +1 -1
- package/dist/generated/personas.js.map +1 -1
- package/dist/index.d.ts +257 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +532 -0
- package/dist/index.js.map +1 -1
- package/dist/index.test.js +149 -1
- package/dist/index.test.js.map +1 -1
- package/package.json +4 -1
package/README.md
CHANGED
|
@@ -10,10 +10,124 @@ npm install @agentworkforce/workload-router
|
|
|
10
10
|
|
|
11
11
|
## Usage
|
|
12
12
|
|
|
13
|
+
### `usePersona(intent, options?)`
|
|
14
|
+
|
|
15
|
+
Despite the `use*` prefix, **this is not a React hook.** It is a plain
|
|
16
|
+
synchronous factory: call it, get back a `PersonaContext` bundling the
|
|
17
|
+
resolved persona, its skill install plan, and an `execute()` closure.
|
|
18
|
+
Nothing is installed, spawned, or written to disk until you call
|
|
19
|
+
`execute()` (or run the install command yourself).
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import { usePersona } from '@agentworkforce/workload-router';
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
There are **two usage modes**, and they are alternatives — not sequential
|
|
26
|
+
steps. Pick one.
|
|
27
|
+
|
|
28
|
+
#### Mode A — let `execute()` install skills and run the agent (recommended)
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
const { execute } = usePersona('npm-provenance');
|
|
32
|
+
|
|
33
|
+
try {
|
|
34
|
+
const result = await execute('Set up npm trusted publishing for this repo', {
|
|
35
|
+
workingDirectory: '.',
|
|
36
|
+
timeoutSeconds: 600,
|
|
37
|
+
});
|
|
38
|
+
// result.status is guaranteed to be 'completed' here — any other
|
|
39
|
+
// outcome is delivered via the catch block below.
|
|
40
|
+
} catch (err) {
|
|
41
|
+
const execErr = err as Error & {
|
|
42
|
+
result?: { status: string; stderr: string; exitCode: number | null };
|
|
43
|
+
};
|
|
44
|
+
console.error(
|
|
45
|
+
'persona run failed',
|
|
46
|
+
execErr.result?.status,
|
|
47
|
+
execErr.result?.stderr,
|
|
48
|
+
);
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`execute()` builds an ad-hoc agent-relay workflow with two steps: (1)
|
|
53
|
+
`prpm install` the persona's skills, then (2) invoke the persona's harness
|
|
54
|
+
agent with your task. `installSkills` defaults to `true`, so the first step
|
|
55
|
+
runs automatically — no manual install needed.
|
|
56
|
+
|
|
57
|
+
> **Outcome contract:** `await execute(...)` only resolves when the
|
|
58
|
+
> persona completes successfully. A non-zero exit from the agent
|
|
59
|
+
> subprocess (or a timeout) throws a `PersonaExecutionError`, and
|
|
60
|
+
> cancellation throws an `AbortError`; both carry the typed
|
|
61
|
+
> `ExecuteResult` on `err.result` so you can inspect
|
|
62
|
+
> `err.result.status`, `err.result.stderr`, `err.result.exitCode`, etc.
|
|
63
|
+
> Wrap `await execute(...)` in `try/catch` whenever you need to
|
|
64
|
+
> observe non-completed outcomes.
|
|
65
|
+
|
|
66
|
+
#### Mode B — pre-stage install out-of-band, then run without re-install
|
|
67
|
+
|
|
13
68
|
```ts
|
|
14
|
-
import {
|
|
69
|
+
import { spawnSync } from 'node:child_process';
|
|
70
|
+
|
|
71
|
+
const { installCommandString, execute } = usePersona('npm-provenance');
|
|
72
|
+
|
|
73
|
+
// build time (Dockerfile RUN, CI bootstrap step, first-run setup, etc.):
|
|
74
|
+
spawnSync(installCommandString, { shell: true, stdio: 'inherit' });
|
|
75
|
+
|
|
76
|
+
// runtime — skip re-install because skills are already staged:
|
|
77
|
+
const result = await execute('Your task', {
|
|
78
|
+
workingDirectory: '.',
|
|
79
|
+
installSkills: false,
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Use Mode B when you want to install skills once at build/CI time for
|
|
84
|
+
caching, hermeticity, offline runtime, or split-trust reasons — or when you
|
|
85
|
+
want to wrap the install with your own process management (custom timeout,
|
|
86
|
+
logging, retry, alternative runner, etc.).
|
|
87
|
+
|
|
88
|
+
A third usage is **install-only**: if all you want is to materialize the
|
|
89
|
+
persona's skills into the repo for a human or another tool to use, run
|
|
90
|
+
`installCommandString` and never call `execute()`.
|
|
91
|
+
|
|
92
|
+
> ⚠️ **Do not combine the two modes without `installSkills: false`.**
|
|
93
|
+
> Running `spawnSync(installCommandString, ...)` *and then* calling
|
|
94
|
+
> `execute(task)` without passing `installSkills: false` will install the
|
|
95
|
+
> persona's skills **twice**. `ExecuteOptions.installSkills` defaults to
|
|
96
|
+
> `true`, so you must explicitly opt out when you have already pre-staged.
|
|
97
|
+
|
|
98
|
+
#### Cancellation, streaming progress, and the run id
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
const abort = new AbortController();
|
|
102
|
+
const run = usePersona('npm-provenance').execute('Your task', {
|
|
103
|
+
signal: abort.signal,
|
|
104
|
+
onProgress: ({ stream, text }) => process[stream].write(text),
|
|
105
|
+
});
|
|
106
|
+
|
|
107
|
+
run.runId.then((id) => console.log('workflow run id:', id));
|
|
108
|
+
|
|
109
|
+
// ...later, from another code path:
|
|
110
|
+
abort.abort(); // or: run.cancel('user requested');
|
|
111
|
+
|
|
112
|
+
try {
|
|
113
|
+
const result = await run; // only returns when status === 'completed'
|
|
114
|
+
} catch (err) {
|
|
115
|
+
// Cancellation throws AbortError; failure throws PersonaExecutionError.
|
|
116
|
+
// Both carry the typed ExecuteResult on `err.result` — inspect
|
|
117
|
+
// `err.result.status`, `err.result.stderr`, `err.result.exitCode`, etc.
|
|
118
|
+
const execErr = err as Error & {
|
|
119
|
+
result?: { status: string; stderr: string; exitCode: number | null };
|
|
120
|
+
};
|
|
121
|
+
console.error('run did not complete', execErr.name, execErr.result?.status);
|
|
122
|
+
}
|
|
15
123
|
```
|
|
16
124
|
|
|
125
|
+
`run.runId` is a `Promise<string>` — it is *not* available synchronously
|
|
126
|
+
when `execute()` returns, because the workflow hasn't started yet. It
|
|
127
|
+
resolves once the persona's agent step has actually spawned (on the first
|
|
128
|
+
progress event from the subprocess, or ~250ms after spawn as a safety net).
|
|
129
|
+
Don't block on it in a tight synchronous path expecting a cached value.
|
|
130
|
+
|
|
17
131
|
## Development
|
|
18
132
|
|
|
19
133
|
```bash
|
|
@@ -223,7 +223,7 @@ export declare const npmProvenancePublisher: {
|
|
|
223
223
|
};
|
|
224
224
|
readonly "best-value": {
|
|
225
225
|
readonly harness: "opencode";
|
|
226
|
-
readonly model: "opencode/
|
|
226
|
+
readonly model: "opencode/minimax-m2.5";
|
|
227
227
|
readonly systemPrompt: "You are an npm release engineer focused on secure publishing. Configure GitHub Actions to publish via OIDC trusted publishing with --provenance attestations, replacing any long-lived NPM_TOKEN. Verify id-token: write permission, repository.url in package.json, npm upgraded to latest before publish, and trusted publisher registration on npmjs.com. Handle monorepos by publishing each package in the correct working directory. Produce concrete workflow diffs. Same security bar as higher tiers; just be more concise. Apply the prpm/npm-trusted-publishing skill for canonical setup guidance.";
|
|
228
228
|
readonly harnessSettings: {
|
|
229
229
|
readonly reasoning: "medium";
|
|
@@ -179,7 +179,7 @@ export const npmProvenancePublisher = {
|
|
|
179
179
|
},
|
|
180
180
|
"best-value": {
|
|
181
181
|
"harness": "opencode",
|
|
182
|
-
"model": "opencode/
|
|
182
|
+
"model": "opencode/minimax-m2.5",
|
|
183
183
|
"systemPrompt": "You are an npm release engineer focused on secure publishing. Configure GitHub Actions to publish via OIDC trusted publishing with --provenance attestations, replacing any long-lived NPM_TOKEN. Verify id-token: write permission, repository.url in package.json, npm upgraded to latest before publish, and trusted publisher registration on npmjs.com. Handle monorepos by publishing each package in the correct working directory. Produce concrete workflow diffs. Same security bar as higher tiers; just be more concise. Apply the prpm/npm-trusted-publishing skill for canonical setup guidance.",
|
|
184
184
|
"harnessSettings": { "reasoning": "medium", "timeoutSeconds": 600 }
|
|
185
185
|
},
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"personas.js","sourceRoot":"","sources":["../../src/generated/personas.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"personas.js","sourceRoot":"","sources":["../../src/generated/personas.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
CHANGED
|
@@ -76,6 +76,186 @@ export interface SkillMaterializationPlan {
|
|
|
76
76
|
harness: Harness;
|
|
77
77
|
installs: SkillInstall[];
|
|
78
78
|
}
|
|
79
|
+
/**
|
|
80
|
+
* Options for {@link PersonaContext.execute}. All fields are optional —
|
|
81
|
+
* calling `execute(task)` with no options is the common case.
|
|
82
|
+
*
|
|
83
|
+
* Pass `installSkills: false` when you have already pre-staged the persona's
|
|
84
|
+
* skills via {@link PersonaContext.installCommandString} (e.g. in a Dockerfile
|
|
85
|
+
* or a CI bootstrap step) and do not want `execute()` to re-install them.
|
|
86
|
+
* Leaving `installSkills` unset means `execute()` installs skills itself as
|
|
87
|
+
* the first step of the ad-hoc workflow — this is the default.
|
|
88
|
+
*/
|
|
89
|
+
export interface ExecuteOptions {
|
|
90
|
+
/** Absolute or repo-relative path the spawned agent should treat as its CWD. */
|
|
91
|
+
workingDirectory?: string;
|
|
92
|
+
/** Optional step name override for the ad-hoc workflow run. */
|
|
93
|
+
name?: string;
|
|
94
|
+
/** Hard timeout for the install + agent run in seconds. */
|
|
95
|
+
timeoutSeconds?: number;
|
|
96
|
+
/** Optional structured context appended to the task body as JSON. */
|
|
97
|
+
inputs?: Record<string, string | number | boolean>;
|
|
98
|
+
/** Install persona skills before execution. Defaults to true. */
|
|
99
|
+
installSkills?: boolean;
|
|
100
|
+
/** Additional environment variables available to install + agent processes. */
|
|
101
|
+
env?: NodeJS.ProcessEnv;
|
|
102
|
+
/** Abort signal for cancellation. */
|
|
103
|
+
signal?: AbortSignal;
|
|
104
|
+
/** Streaming stdout/stderr callback from install + agent subprocesses. */
|
|
105
|
+
onProgress?: (chunk: {
|
|
106
|
+
stream: 'stdout' | 'stderr';
|
|
107
|
+
text: string;
|
|
108
|
+
}) => void;
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Final result of a {@link PersonaContext.execute} call.
|
|
112
|
+
*
|
|
113
|
+
* **Only `status: 'completed'` is returned as a resolved promise.** Any
|
|
114
|
+
* other outcome is delivered as a thrown error with a typed `.result`
|
|
115
|
+
* property carrying this interface, so callers can `try/catch` and then
|
|
116
|
+
* inspect `err.result.status`, `err.result.stderr`, `err.result.exitCode`
|
|
117
|
+
* etc. just as they would read the resolved value:
|
|
118
|
+
*
|
|
119
|
+
* - `status: 'failed'` — the agent subprocess exited non-zero, or the
|
|
120
|
+
* workflow settled in a failed state for any other reason. Thrown as
|
|
121
|
+
* a {@link PersonaExecutionError}.
|
|
122
|
+
* - `status: 'timeout'` — the workflow's hard timeout fired before the
|
|
123
|
+
* run completed. Also thrown as a {@link PersonaExecutionError} (the
|
|
124
|
+
* status is derived from the underlying timeout error).
|
|
125
|
+
* - `status: 'cancelled'` — the caller aborted via
|
|
126
|
+
* {@link ExecuteOptions.signal} or {@link PersonaExecution.cancel}.
|
|
127
|
+
* Thrown as an `AbortError` (with `error.result.status === 'cancelled'`).
|
|
128
|
+
*
|
|
129
|
+
* So the typical shape of a caller is:
|
|
130
|
+
*
|
|
131
|
+
* ```ts
|
|
132
|
+
* try {
|
|
133
|
+
* const result = await execute(task, opts);
|
|
134
|
+
* // result.status is guaranteed to be 'completed' here.
|
|
135
|
+
* } catch (err) {
|
|
136
|
+
* // err.result.status is 'failed' | 'cancelled' | 'timeout'.
|
|
137
|
+
* // err.result.stderr / err.result.exitCode are populated from
|
|
138
|
+
* // whatever the agent subprocess produced.
|
|
139
|
+
* }
|
|
140
|
+
* ```
|
|
141
|
+
*/
|
|
142
|
+
export interface ExecuteResult {
|
|
143
|
+
status: 'completed' | 'failed' | 'cancelled' | 'timeout';
|
|
144
|
+
output: string;
|
|
145
|
+
stderr: string;
|
|
146
|
+
exitCode: number | null;
|
|
147
|
+
durationMs: number;
|
|
148
|
+
workflowRunId?: string;
|
|
149
|
+
stepName: string;
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Handle returned by {@link PersonaContext.execute}. It *is* a `Promise<ExecuteResult>`
|
|
153
|
+
* (awaitable directly), with two extra members bolted on:
|
|
154
|
+
*
|
|
155
|
+
* - `cancel(reason?)` — request cancellation of the running workflow. Equivalent
|
|
156
|
+
* to aborting the `AbortSignal` passed via {@link ExecuteOptions.signal}. Safe
|
|
157
|
+
* to call after the run has already settled (no-op).
|
|
158
|
+
*
|
|
159
|
+
* - `runId` — a `Promise<string>` that resolves to the workflow run id
|
|
160
|
+
* once the persona's agent step has actually spawned. This is deliberately
|
|
161
|
+
* a promise (not `string | undefined`) because the id is not known at the
|
|
162
|
+
* moment `execute()` returns — the workflow hasn't started yet. The
|
|
163
|
+
* resolution timing contract is:
|
|
164
|
+
*
|
|
165
|
+
* 1. If the agent subprocess emits any stdout/stderr, `runId` resolves
|
|
166
|
+
* immediately on the first progress event (see `onStepProgress`).
|
|
167
|
+
* 2. Otherwise, it resolves ~250ms after the agent step spawns (safety
|
|
168
|
+
* net armed in `onStepSpawn`, see `src/index.ts` around the
|
|
169
|
+
* `runIdReadyTimer` definition).
|
|
170
|
+
* 3. If the run settles (completes/fails/cancels) before either of the
|
|
171
|
+
* above fire, it resolves at settle time with the final run id.
|
|
172
|
+
*
|
|
173
|
+
* Practical consequence: `await run.runId` is *not* instantaneous — do not
|
|
174
|
+
* block on it in a tight synchronous path expecting a cached value.
|
|
175
|
+
*
|
|
176
|
+
* Error mirroring: if `execute()` fails before the workflow has started
|
|
177
|
+
* (e.g. the dynamic `@agent-relay/sdk/workflows` import throws, or the
|
|
178
|
+
* `WorkflowRunner` constructor throws), `runId` rejects with the same
|
|
179
|
+
* error as the main promise. Awaiting `runId` is therefore safe to
|
|
180
|
+
* `try/catch` — you will observe the same failure twice, not miss it.
|
|
181
|
+
* Note that you are not required to observe `runId`; the main promise
|
|
182
|
+
* is the authoritative outcome channel, and the auxiliary rejection
|
|
183
|
+
* on `runId` is internally suppressed when no handler is attached.
|
|
184
|
+
*/
|
|
185
|
+
export interface PersonaExecution extends Promise<ExecuteResult> {
|
|
186
|
+
cancel(reason?: string): void;
|
|
187
|
+
readonly runId: Promise<string>;
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* Return value of {@link usePersona}. A side-effect-free bundle of
|
|
191
|
+
* "what this persona is" plus an `execute()` closure for running it.
|
|
192
|
+
*
|
|
193
|
+
* There are two ways to use the fields, and they are **alternatives**,
|
|
194
|
+
* not sequential steps:
|
|
195
|
+
*
|
|
196
|
+
* **Mode A — let `execute()` handle install (recommended default):**
|
|
197
|
+
* ```ts
|
|
198
|
+
* const { execute } = usePersona('npm-provenance');
|
|
199
|
+
* const result = await execute('Your task', { workingDirectory: '.' });
|
|
200
|
+
* ```
|
|
201
|
+
* `execute()` installs the persona's skills as the first step of its
|
|
202
|
+
* ad-hoc workflow, then runs the agent task. No manual install needed.
|
|
203
|
+
*
|
|
204
|
+
* **Mode B — pre-stage install yourself, then `execute()` without re-install:**
|
|
205
|
+
* ```ts
|
|
206
|
+
* const { installCommandString, execute } = usePersona('npm-provenance');
|
|
207
|
+
* // e.g. inside a Dockerfile RUN, or a CI bootstrap step:
|
|
208
|
+
* spawnSync(installCommandString, { shell: true, stdio: 'inherit' });
|
|
209
|
+
* // then, at runtime:
|
|
210
|
+
* const result = await execute('Your task', {
|
|
211
|
+
* workingDirectory: '.',
|
|
212
|
+
* installSkills: false, // skip re-install; skills are already staged
|
|
213
|
+
* });
|
|
214
|
+
* ```
|
|
215
|
+
* Use this when you want to install skills once at build/CI time for
|
|
216
|
+
* caching, hermeticity, offline runtime, or split-trust reasons — or
|
|
217
|
+
* when you want to wrap the install with your own process management
|
|
218
|
+
* (custom timeout, logging, retry, alternative runner, etc.).
|
|
219
|
+
*
|
|
220
|
+
* In both modes, the `await execute(...)` call above **only resolves
|
|
221
|
+
* when `status === 'completed'`**. Non-zero exits / timeouts throw a
|
|
222
|
+
* {@link PersonaExecutionError}, and cancellation throws an `AbortError`;
|
|
223
|
+
* both carry a typed `.result` for inspection. See {@link ExecuteResult}
|
|
224
|
+
* for the full outcome contract.
|
|
225
|
+
*
|
|
226
|
+
* ⚠️ **Do not combine the two modes without `installSkills: false`.**
|
|
227
|
+
* Running `spawnSync(installCommandString, ...)` *and then* calling
|
|
228
|
+
* `execute(task)` without passing `installSkills: false` will install
|
|
229
|
+
* the persona's skills twice. The default value of `installSkills` is
|
|
230
|
+
* `true` (see {@link ExecuteOptions}).
|
|
231
|
+
*
|
|
232
|
+
* A third usage is install-only: if all you want is to materialize
|
|
233
|
+
* the persona's skills into the repo (for a human or another tool
|
|
234
|
+
* to use), run `installCommandString` and never call `execute()`.
|
|
235
|
+
*/
|
|
236
|
+
export interface PersonaContext {
|
|
237
|
+
/** Resolved persona: id, tier, runtime (harness + model), and skills. */
|
|
238
|
+
readonly selection: PersonaSelection;
|
|
239
|
+
/** Pure plan of what would be installed and where (no side effects). */
|
|
240
|
+
readonly installPlan: SkillMaterializationPlan;
|
|
241
|
+
/** argv form of the install command — safer for `execFile`/`spawn` callers. */
|
|
242
|
+
readonly installCommand: readonly string[];
|
|
243
|
+
/** Shell-escaped form of the install command — convenient for `spawn(..., { shell: true })`. */
|
|
244
|
+
readonly installCommandString: string;
|
|
245
|
+
/**
|
|
246
|
+
* Run the persona against `task`. Builds an ad-hoc agent-relay workflow,
|
|
247
|
+
* optionally runs `prpm install` as its first step (see
|
|
248
|
+
* {@link ExecuteOptions.installSkills}, default `true`), then invokes the
|
|
249
|
+
* persona's harness agent with the task. Returns a {@link PersonaExecution}
|
|
250
|
+
* (an awaitable promise with `cancel()` and `runId` attached).
|
|
251
|
+
*/
|
|
252
|
+
execute(task: string, options?: ExecuteOptions): PersonaExecution;
|
|
253
|
+
}
|
|
254
|
+
export declare class PersonaExecutionError extends Error {
|
|
255
|
+
readonly result: ExecuteResult;
|
|
256
|
+
cause?: unknown;
|
|
257
|
+
constructor(message: string, result: ExecuteResult, cause?: unknown);
|
|
258
|
+
}
|
|
79
259
|
/**
|
|
80
260
|
* Given a set of persona skills and the harness the persona will run under,
|
|
81
261
|
* produce the concrete install plan: which `prpm install` invocations to run
|
|
@@ -100,5 +280,82 @@ export declare function resolvePersona(intent: PersonaIntent, profile?: RoutingP
|
|
|
100
280
|
* Prefer resolvePersona(intent, profile) for policy-driven selection.
|
|
101
281
|
*/
|
|
102
282
|
export declare function resolvePersonaByTier(intent: PersonaIntent, tier?: PersonaTier): PersonaSelection;
|
|
283
|
+
/**
|
|
284
|
+
* Resolve a persona for `intent` and return a {@link PersonaContext}
|
|
285
|
+
* bundling the resolved persona, its skill install plan, and an
|
|
286
|
+
* `execute()` closure for running the persona against a task.
|
|
287
|
+
*
|
|
288
|
+
* **This is not a React hook.** The `use*` prefix is unfortunate — it is
|
|
289
|
+
* a plain synchronous factory with no implicit state, no side effects,
|
|
290
|
+
* and no rules-of-hooks constraints. Calling `usePersona(intent)` does
|
|
291
|
+
* nothing but resolve routing config and pre-compute the install plan.
|
|
292
|
+
* Nothing is installed, spawned, or written to disk until you call
|
|
293
|
+
* `execute()` (or run the install command yourself).
|
|
294
|
+
*
|
|
295
|
+
* See {@link PersonaContext} for the two usage modes (let `execute()`
|
|
296
|
+
* handle install vs. pre-stage install and pass `installSkills: false`)
|
|
297
|
+
* and the double-install caveat.
|
|
298
|
+
*
|
|
299
|
+
* @example
|
|
300
|
+
* // Mode A — let execute() install skills and run the agent in one call.
|
|
301
|
+
* // Only `status: 'completed'` resolves; non-zero exits / timeouts throw
|
|
302
|
+
* // PersonaExecutionError and cancellation throws AbortError, both with
|
|
303
|
+
* // the typed ExecuteResult attached as `err.result`.
|
|
304
|
+
* const { execute } = usePersona('npm-provenance');
|
|
305
|
+
* try {
|
|
306
|
+
* const result = await execute('Set up npm trusted publishing for this repo', {
|
|
307
|
+
* workingDirectory: '.',
|
|
308
|
+
* timeoutSeconds: 600,
|
|
309
|
+
* });
|
|
310
|
+
* // result.status === 'completed' here
|
|
311
|
+
* } catch (err) {
|
|
312
|
+
* const execErr = err as Error & { result?: ExecuteResult };
|
|
313
|
+
* console.error('persona run failed', execErr.result?.status, execErr.result?.stderr);
|
|
314
|
+
* }
|
|
315
|
+
*
|
|
316
|
+
* @example
|
|
317
|
+
* // Mode B — pre-stage install out-of-band (e.g. in a Dockerfile), then
|
|
318
|
+
* // run at runtime without re-installing:
|
|
319
|
+
* const { installCommandString, execute } = usePersona('npm-provenance');
|
|
320
|
+
* // build/CI step:
|
|
321
|
+
* spawnSync(installCommandString, { shell: true, stdio: 'inherit' });
|
|
322
|
+
* // runtime step:
|
|
323
|
+
* const result = await execute('Your task', {
|
|
324
|
+
* workingDirectory: '.',
|
|
325
|
+
* installSkills: false,
|
|
326
|
+
* });
|
|
327
|
+
*
|
|
328
|
+
* @example
|
|
329
|
+
* // Cancellation + streaming progress. Aborting causes `await run` to
|
|
330
|
+
* // throw an AbortError with `err.result.status === 'cancelled'`, so
|
|
331
|
+
* // wrap in try/catch if you plan to abort.
|
|
332
|
+
* const abort = new AbortController();
|
|
333
|
+
* const run = usePersona('npm-provenance').execute('Your task', {
|
|
334
|
+
* signal: abort.signal,
|
|
335
|
+
* onProgress: ({ stream, text }) => process[stream].write(text),
|
|
336
|
+
* });
|
|
337
|
+
* run.runId.then((id) => console.log('workflow run id:', id));
|
|
338
|
+
* // ...later:
|
|
339
|
+
* abort.abort(); // or: run.cancel('user requested');
|
|
340
|
+
* try {
|
|
341
|
+
* const result = await run;
|
|
342
|
+
* // result.status === 'completed'
|
|
343
|
+
* } catch (err) {
|
|
344
|
+
* const execErr = err as Error & { result?: ExecuteResult };
|
|
345
|
+
* // execErr.name === 'AbortError' and execErr.result?.status === 'cancelled'
|
|
346
|
+
* }
|
|
347
|
+
*
|
|
348
|
+
* @param intent The persona intent to resolve (e.g. `'npm-provenance'`).
|
|
349
|
+
* @param options Optional overrides. `harness` forces a specific harness
|
|
350
|
+
* (otherwise inferred from the selected tier's runtime).
|
|
351
|
+
* `tier` bypasses profile-driven routing and selects a tier
|
|
352
|
+
* directly (legacy path — prefer `profile`). `profile`
|
|
353
|
+
* selects the routing profile (defaults to `'default'`).
|
|
354
|
+
*/
|
|
355
|
+
export declare function usePersona(intent: PersonaIntent, options?: {
|
|
356
|
+
harness?: Harness;
|
|
357
|
+
tier?: PersonaTier;
|
|
358
|
+
profile?: RoutingProfile | RoutingProfileId;
|
|
359
|
+
}): PersonaContext;
|
|
103
360
|
export * from './eval.js';
|
|
104
361
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|