@patchbay-nebius/agent 0.0.0-stage → 0.1.0

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.
@@ -0,0 +1,302 @@
1
+ interface ModelTier {
2
+ id: string;
3
+ /** USD per million tokens, used for the cost readout. */
4
+ inputPrice: number;
5
+ outputPrice: number;
6
+ }
7
+ interface AgentConfig {
8
+ mock: boolean;
9
+ /** `nebius` (isolated sandbox, default) or `local` (dev fallback, not isolated). */
10
+ runner: 'nebius' | 'local';
11
+ nebiusApiKey: string;
12
+ nebiusProject: string;
13
+ nebiusBaseUrl: string;
14
+ sandboxUrl: string;
15
+ tavilyApiKey: string;
16
+ baseImage: string | undefined;
17
+ maxAttempts: number;
18
+ /** How many repair variants to try in parallel per attempt. 1 = classic sequential repair. */
19
+ parallelRepairs: number;
20
+ /**
21
+ * LLM provider identity, chosen by setting PATCHBAY_LLM_PROVIDER. Default `nebius` keeps
22
+ * the Nemotron-specific `chat_template_kwargs: { enable_thinking: false }` field in requests;
23
+ * `openai` / `generic` strip it so any other OpenAI-compatible endpoint (OpenAI, Groq,
24
+ * Together, Fireworks, OpenRouter, self-hosted vLLM) stops rejecting it.
25
+ */
26
+ llmProvider: 'nebius' | 'openai' | 'generic';
27
+ models: {
28
+ fast: ModelTier;
29
+ mid: ModelTier;
30
+ strong: ModelTier;
31
+ };
32
+ }
33
+ type Env = Record<string, string | undefined>;
34
+ declare function loadConfig(env?: Env): AgentConfig;
35
+ declare function missingLiveKeys(config: AgentConfig): string[];
36
+
37
+ type StepId = 'plan' | 'research' | 'generate' | 'verify' | 'package';
38
+ interface Plan {
39
+ summary: string;
40
+ source: {
41
+ app: string;
42
+ trigger: string;
43
+ docsQuery: string;
44
+ };
45
+ target: {
46
+ app: string;
47
+ action: string;
48
+ docsQuery: string;
49
+ };
50
+ /**
51
+ * Extra target apps the connector must also call, in the order it will call them.
52
+ * Lets a single run cover chained flows like "Zendesk → GitHub → Zendesk comment"
53
+ * or "HubSpot → Google OAuth refresh → Google Sheets" where more than one external
54
+ * service is reached. Each entry is researched and gets its own endpoints in the spec.
55
+ */
56
+ additionalTargets?: {
57
+ app: string;
58
+ action: string;
59
+ docsQuery: string;
60
+ }[];
61
+ fieldMapping: {
62
+ from: string;
63
+ to: string;
64
+ note?: string;
65
+ }[];
66
+ assumptions: string[];
67
+ }
68
+ interface AuthSpec {
69
+ type: 'header' | 'bearer' | 'query' | 'basic' | 'none';
70
+ /** Header or query parameter name, e.g. `x-api-token` or `api_token`. */
71
+ name?: string;
72
+ /** Environment variable the generated connector reads the secret from. */
73
+ envVar: string;
74
+ }
75
+ interface EndpointSpec {
76
+ app: string;
77
+ role: 'source' | 'target';
78
+ method: string;
79
+ url: string;
80
+ auth: AuthSpec;
81
+ /** Minimal but realistic example of the request body (target) or event payload (source). */
82
+ example: unknown;
83
+ /** Example of what the endpoint returns, when the connector needs the response. */
84
+ responseExample?: unknown;
85
+ docsUrl: string;
86
+ notes: string[];
87
+ }
88
+ interface ApiSpec {
89
+ source: EndpointSpec;
90
+ target: EndpointSpec[];
91
+ }
92
+ interface Source {
93
+ title: string;
94
+ url: string;
95
+ /** The page is on the vendor's own domain. */
96
+ official?: boolean;
97
+ }
98
+ interface GeneratedFile {
99
+ path: string;
100
+ content: string;
101
+ }
102
+ interface TestFailure {
103
+ name: string;
104
+ message: string;
105
+ }
106
+ interface TestReport {
107
+ typecheckOk: boolean;
108
+ typecheckOutput: string;
109
+ passed: number;
110
+ failed: number;
111
+ total: number;
112
+ failures: TestFailure[];
113
+ durationMs: number;
114
+ /** Where the tests ran: a Nebius sandbox operation id, `local`, or `replay`. */
115
+ ranOn: string;
116
+ /** Did the suite run the connector against the documented example payload, and did that pass? */
117
+ contract?: 'passed' | 'failed' | 'missing';
118
+ /** Full names of the tests that passed. */
119
+ passedNames?: string[];
120
+ }
121
+ interface Usage {
122
+ model: string;
123
+ promptTokens: number;
124
+ completionTokens: number;
125
+ costUsd: number;
126
+ }
127
+ type RunEvent = {
128
+ type: 'mode';
129
+ mode: 'live' | 'replay';
130
+ } | {
131
+ type: 'step';
132
+ step: StepId;
133
+ status: 'start' | 'done' | 'error';
134
+ detail?: string;
135
+ } | {
136
+ type: 'log';
137
+ step: StepId;
138
+ message: string;
139
+ } | {
140
+ type: 'plan';
141
+ plan: Plan;
142
+ } | {
143
+ type: 'sources';
144
+ sources: Source[];
145
+ } | {
146
+ type: 'spec';
147
+ spec: ApiSpec;
148
+ } | {
149
+ type: 'files';
150
+ attempt: number;
151
+ files: GeneratedFile[];
152
+ } | {
153
+ type: 'tests';
154
+ attempt: number;
155
+ report: TestReport;
156
+ branches?: Array<{
157
+ branch: number;
158
+ passed: number;
159
+ total: number;
160
+ typecheckOk: boolean;
161
+ green: boolean;
162
+ }>;
163
+ } | {
164
+ type: 'usage';
165
+ usage: Usage[];
166
+ } | {
167
+ type: 'result';
168
+ ok: boolean;
169
+ attempts: number;
170
+ files: GeneratedFile[];
171
+ report: TestReport | null;
172
+ } | {
173
+ type: 'error';
174
+ message: string;
175
+ };
176
+
177
+ interface RecordedRun {
178
+ prompt: string;
179
+ /** `fixture` for the bundled example, `live` for runs captured with `npm run agent -- --record`. */
180
+ origin: 'fixture' | 'live';
181
+ events: RunEvent[];
182
+ }
183
+ declare const REPLAY_RUN: RecordedRun;
184
+ /** Streams a recorded run with short pauses so the UI shows the same progression as a live run. */
185
+ declare function replayRun(run?: RecordedRun, pace?: number): AsyncGenerator<RunEvent>;
186
+
187
+ interface ChatMessage {
188
+ role: 'system' | 'user' | 'assistant';
189
+ content: string;
190
+ }
191
+ interface ChatOptions {
192
+ temperature?: number;
193
+ /** Includes reasoning tokens when thinking is on, so leave generous headroom. */
194
+ maxTokens?: number;
195
+ /**
196
+ * Nemotron reasons before answering by default. Structured steps (plan, spec) turn it off:
197
+ * the answer is immediate and the token budget goes to the JSON, not to deliberation.
198
+ */
199
+ thinking?: boolean;
200
+ }
201
+ interface LlmClient {
202
+ chat(model: ModelTier, messages: ChatMessage[], options?: ChatOptions): Promise<string>;
203
+ usage(): Usage[];
204
+ }
205
+
206
+ interface RepairContext {
207
+ /** 1-based: the attempt we are producing the fix FOR (so the repair output will be verified as this attempt). */
208
+ attempt: number;
209
+ /** The absolute cap; the agent gives up after this many attempts. */
210
+ maxAttempts: number;
211
+ /** Short lines describing what previous attempts tried and still failed on. Chronological. */
212
+ previousAttempts?: Array<{
213
+ attempt: number;
214
+ summary: string;
215
+ }>;
216
+ }
217
+
218
+ interface SandboxRunner {
219
+ /** Returns an image id that has node, typescript and vitest installed under /work. */
220
+ prepare(log: (message: string) => void): Promise<string>;
221
+ /** Runs typecheck + tests for the given files on a fresh branch of the prepared image. */
222
+ runTests(baseImage: string, files: GeneratedFile[], log: (message: string) => void): Promise<TestReport>;
223
+ }
224
+
225
+ interface SearchHit {
226
+ title: string;
227
+ url: string;
228
+ content: string;
229
+ score: number;
230
+ }
231
+ interface ExtractedPage {
232
+ url: string;
233
+ content: string;
234
+ }
235
+ interface SearchClient {
236
+ search(query: string, options?: {
237
+ maxResults?: number;
238
+ includeDomains?: string[];
239
+ }): Promise<SearchHit[]>;
240
+ extract(urls: string[]): Promise<ExtractedPage[]>;
241
+ }
242
+
243
+ interface AgentDeps {
244
+ config: AgentConfig;
245
+ llm: LlmClient;
246
+ search: SearchClient;
247
+ sandbox: SandboxRunner;
248
+ }
249
+ /**
250
+ * plan (fast model) → research (Tavily + mid model) → generate (strong model)
251
+ * → verify in a Nebius sandbox → repair with the failures, up to maxAttempts.
252
+ */
253
+ declare function runAgent(prompt: string, deps: AgentDeps): AsyncGenerator<RunEvent>;
254
+ /** plan → research only, ends with the spec. No code generation, no sandbox. */
255
+ declare function researchAgent(prompt: string, deps: Omit<AgentDeps, 'sandbox'>): AsyncGenerator<RunEvent>;
256
+ /** verify + repair loop for already-generated files. Uses sandbox + strong model. */
257
+ declare function verifyAgent(files: GeneratedFile[], deps: Omit<AgentDeps, 'search'>): AsyncGenerator<RunEvent>;
258
+ declare function makePlan(prompt: string, llm: LlmClient, config: AgentConfig): Promise<Plan>;
259
+ declare function research(plan: Plan, search: SearchClient, llm: LlmClient, config: AgentConfig, log: (m: string) => void): Promise<{
260
+ spec: ApiSpec;
261
+ sources: Source[];
262
+ }>;
263
+ declare function generate(plan: Plan, spec: ApiSpec, fixtures: string, llm: LlmClient, config: AgentConfig): Promise<GeneratedFile[]>;
264
+ declare function repair(files: GeneratedFile[], report: TestReport, llm: LlmClient, config: AgentConfig, options?: {
265
+ temperature?: number;
266
+ context?: RepairContext;
267
+ }): Promise<GeneratedFile[]>;
268
+ /**
269
+ * Generates up to N repair variants in parallel (different temperatures), verifies all of them
270
+ * in parallel sandbox forks of the same checkpoint, and picks the first green one (or the one
271
+ * with the most passed tests when none is green).
272
+ */
273
+ declare function repairParallel(files: GeneratedFile[], report: TestReport, deps: {
274
+ llm: LlmClient;
275
+ sandbox: SandboxRunner;
276
+ config: AgentConfig;
277
+ baseImage: string;
278
+ withFixtures: (files: GeneratedFile[]) => GeneratedFile[];
279
+ context?: RepairContext;
280
+ }, log: (m: string) => void): Promise<{
281
+ files: GeneratedFile[];
282
+ report: TestReport;
283
+ branches: Array<{
284
+ branch: number;
285
+ passed: number;
286
+ total: number;
287
+ typecheckOk: boolean;
288
+ green: boolean;
289
+ }>;
290
+ }>;
291
+
292
+ declare function parseTestOutput(stdout: string, ranOn: string): TestReport;
293
+ declare function isGreen(report: TestReport): boolean;
294
+
295
+ /** Live run when keys are configured and mock mode is off, otherwise the recorded replay. */
296
+ declare function startRun(prompt: string, config?: AgentConfig): AsyncGenerator<RunEvent>;
297
+ /** Plan + research only. Live if keys are set; the replay stream truncated after `spec` otherwise. */
298
+ declare function startResearch(prompt: string, config?: AgentConfig): AsyncGenerator<RunEvent>;
299
+ /** Verify + repair for given files. Requires live keys; throws in mock mode. */
300
+ declare function startVerify(files: GeneratedFile[], config?: AgentConfig): AsyncGenerator<RunEvent>;
301
+
302
+ export { type AgentDeps, type ApiSpec, type AuthSpec, type EndpointSpec, type GeneratedFile, type Plan, REPLAY_RUN, type RecordedRun, type RunEvent, type Source, type StepId, type TestFailure, type TestReport, type Usage, generate, isGreen, loadConfig, makePlan, missingLiveKeys, parseTestOutput, repair, repairParallel, replayRun, research, researchAgent, runAgent, startResearch, startRun, startVerify, verifyAgent };
package/dist/index.js ADDED
@@ -0,0 +1,39 @@
1
+ import {
2
+ REPLAY_RUN,
3
+ generate,
4
+ isGreen,
5
+ loadConfig,
6
+ makePlan,
7
+ missingLiveKeys,
8
+ parseTestOutput,
9
+ repair,
10
+ repairParallel,
11
+ replayRun,
12
+ research,
13
+ researchAgent,
14
+ runAgent,
15
+ startResearch,
16
+ startRun,
17
+ startVerify,
18
+ verifyAgent
19
+ } from "./chunk-JVXVCXNZ.js";
20
+ export {
21
+ REPLAY_RUN,
22
+ generate,
23
+ isGreen,
24
+ loadConfig,
25
+ makePlan,
26
+ missingLiveKeys,
27
+ parseTestOutput,
28
+ repair,
29
+ repairParallel,
30
+ replayRun,
31
+ research,
32
+ researchAgent,
33
+ runAgent,
34
+ startResearch,
35
+ startRun,
36
+ startVerify,
37
+ verifyAgent
38
+ };
39
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
package/package.json CHANGED
@@ -1,6 +1,63 @@
1
1
  {
2
2
  "name": "@patchbay-nebius/agent",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Describe an integration in one sentence, get a tested TypeScript connector. Nemotron on Nebius + Tavily + Nebius Sandboxes.",
5
+ "keywords": [
6
+ "patchbay",
7
+ "codegen",
8
+ "connector",
9
+ "integration",
10
+ "nebius",
11
+ "nemotron",
12
+ "tavily",
13
+ "sandbox",
14
+ "typescript",
15
+ "agent"
16
+ ],
17
+ "author": "Sarah Vogel <vogels671@gmail.com>",
18
+ "license": "MIT",
19
+ "homepage": "https://github.com/GodSmasher/patchbay",
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "git+https://github.com/GodSmasher/patchbay.git",
23
+ "directory": "packages/agent"
24
+ },
25
+ "bugs": {
26
+ "url": "https://github.com/GodSmasher/patchbay/issues"
27
+ },
28
+ "type": "module",
29
+ "main": "./dist/index.js",
30
+ "types": "./dist/index.d.ts",
31
+ "bin": {
32
+ "patchbay": "dist/cli.js"
33
+ },
34
+ "exports": {
35
+ ".": {
36
+ "import": "./dist/index.js",
37
+ "types": "./dist/index.d.ts"
38
+ },
39
+ "./cli": {
40
+ "import": "./dist/cli.js",
41
+ "types": "./dist/cli.d.ts"
42
+ }
43
+ },
44
+ "files": [
45
+ "dist",
46
+ "README.md",
47
+ "LICENSE"
48
+ ],
49
+ "publishConfig": {
50
+ "access": "public"
51
+ },
52
+ "scripts": {
53
+ "build": "tsup",
54
+ "typecheck": "tsc --noEmit -p .",
55
+ "prepublishOnly": "npm run build"
56
+ },
57
+ "dependencies": {
58
+ "esbuild": "^0.28.2"
59
+ },
60
+ "devDependencies": {
61
+ "tsup": "^8.5.1"
62
+ }
63
+ }