@howone/agent-cli 0.5.3 → 0.5.5
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 +2 -0
- package/bin/index.mjs +121 -63
- package/package.json +1 -1
- package/skills/howone/02-develop.md +2 -0
- package/skills/howone/03-workflows.md +4 -0
- package/skills/howone/04-functions-and-data.md +5 -2
- package/skills/howone/SKILL.md +8 -0
- package/templates/vite/.howone/skills/howone/03-ai-capabilities/01-ai-capability-architecture.md +4 -0
- package/templates/vite/.howone/skills/howone/03-ai-capabilities/06-functions.md +150 -0
- package/templates/vite/.npmrc.template +2 -0
- package/templates/vite/AGENTS.md +1 -0
package/README.md
CHANGED
|
@@ -33,6 +33,8 @@ howone workflows search "海报" && howone workflows run <app>/<workflow> --inpu
|
|
|
33
33
|
(原来在 SDK 的 `.agents/skills`,拆仓时移过来了)。沙箱里 `howone init app` 生成的工作区直接带上这一份。
|
|
34
34
|
|
|
35
35
|
`templates/vite/package.json` 里锁的 `@howone/sdk` 版本要和已发布的 SDK 一致。
|
|
36
|
+
模板自带无凭据的 `.npmrc`,把 `@howone/*` 指向 HowOne 私有 npm 仓库;使用者需在自己的
|
|
37
|
+
npm 配置中提供该仓库的登录凭据,CLI 不会把 token 写进项目或模板。
|
|
36
38
|
|
|
37
39
|
## npm 安装
|
|
38
40
|
|
package/bin/index.mjs
CHANGED
|
@@ -202,49 +202,54 @@ async function networkFetch(url, init) {
|
|
|
202
202
|
return await fetch(target, init);
|
|
203
203
|
} catch (error) {
|
|
204
204
|
if (init?.signal?.aborted) throw error;
|
|
205
|
-
|
|
206
|
-
const seen = /* @__PURE__ */ new Set();
|
|
207
|
-
function visit(value) {
|
|
208
|
-
if (!(value instanceof Error) || seen.has(value) || seen.size >= 16) return;
|
|
209
|
-
seen.add(value);
|
|
210
|
-
const code = value.code;
|
|
211
|
-
if (typeof code === "string" && /^[A-Z][A-Z0-9_]+$/.test(code)) codes.add(code);
|
|
212
|
-
visit(value.cause);
|
|
213
|
-
if (value instanceof AggregateError) for (const child of value.errors) visit(child);
|
|
214
|
-
}
|
|
215
|
-
visit(error);
|
|
216
|
-
const has = (...values) => values.some((code) => codes.has(code));
|
|
217
|
-
let stage = "connection";
|
|
218
|
-
let hint = "Check VPN routing and whether Node.js uses the same proxy as your browser.";
|
|
219
|
-
if (has("ENOTFOUND", "EAI_AGAIN", "EAI_NONAME")) {
|
|
220
|
-
stage = "dns";
|
|
221
|
-
hint = "DNS lookup failed. Check that your VPN provides DNS for this domain. On macOS, run scutil --dns.";
|
|
222
|
-
} else if ([...codes].some((code) => /CERT|SELF_SIGNED|UNABLE_TO_VERIFY|UNABLE_TO_GET_ISSUER|^ERR_SSL_/.test(code))) {
|
|
223
|
-
stage = "tls";
|
|
224
|
-
hint = "TLS failed. Check the certificate hostname and expiry. For a trusted company CA, try NODE_USE_SYSTEM_CA=1 on supported Node versions or set NODE_EXTRA_CA_CERTS to the company CA PEM file.";
|
|
225
|
-
} else if (has("ETIMEDOUT", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT")) hint = "Connection timed out. Check the VPN route, firewall and proxy.";
|
|
226
|
-
else if (has("ECONNREFUSED", "ECONNRESET", "UND_ERR_SOCKET", "EPIPE")) hint = "Connection refused or closed. Check that the server and any configured proxy are reachable.";
|
|
227
|
-
const method = init?.method ?? "GET";
|
|
228
|
-
const endpoint = target.origin + target.pathname;
|
|
229
|
-
const reason = [...codes].join(", ") || "no system error code reported";
|
|
230
|
-
throw new CliError("E_NETWORK", `${method} ${endpoint} failed (${stage}: ${reason}). ${hint}`, {
|
|
231
|
-
method,
|
|
232
|
-
endpoint,
|
|
233
|
-
stage,
|
|
234
|
-
codes: [...codes],
|
|
235
|
-
hint,
|
|
236
|
-
nodeVersion: process.version,
|
|
237
|
-
proxyEnvironment: [
|
|
238
|
-
"HTTPS_PROXY",
|
|
239
|
-
"HTTP_PROXY",
|
|
240
|
-
"ALL_PROXY",
|
|
241
|
-
"https_proxy",
|
|
242
|
-
"http_proxy",
|
|
243
|
-
"all_proxy"
|
|
244
|
-
].filter((key) => Boolean(process.env[key]))
|
|
245
|
-
});
|
|
205
|
+
throw networkError(url, init, error);
|
|
246
206
|
}
|
|
247
207
|
}
|
|
208
|
+
/** Format transport errors without exposing credentials or query strings. */
|
|
209
|
+
function networkError(url, init, error) {
|
|
210
|
+
const target = new URL(url);
|
|
211
|
+
const codes = /* @__PURE__ */ new Set();
|
|
212
|
+
const seen = /* @__PURE__ */ new Set();
|
|
213
|
+
function visit(value) {
|
|
214
|
+
if (!(value instanceof Error) || seen.has(value) || seen.size >= 16) return;
|
|
215
|
+
seen.add(value);
|
|
216
|
+
const code = value.code;
|
|
217
|
+
if (typeof code === "string" && /^[A-Z][A-Z0-9_]+$/.test(code)) codes.add(code);
|
|
218
|
+
visit(value.cause);
|
|
219
|
+
if (value instanceof AggregateError) for (const child of value.errors) visit(child);
|
|
220
|
+
}
|
|
221
|
+
visit(error);
|
|
222
|
+
const has = (...values) => values.some((code) => codes.has(code));
|
|
223
|
+
let stage = "connection";
|
|
224
|
+
let hint = "Check VPN routing and whether Node.js uses the same proxy as your browser.";
|
|
225
|
+
if (has("ENOTFOUND", "EAI_AGAIN", "EAI_NONAME")) {
|
|
226
|
+
stage = "dns";
|
|
227
|
+
hint = "DNS lookup failed. Check that your VPN provides DNS for this domain. On macOS, run scutil --dns.";
|
|
228
|
+
} else if ([...codes].some((code) => /CERT|SELF_SIGNED|UNABLE_TO_VERIFY|UNABLE_TO_GET_ISSUER|^ERR_SSL_/.test(code))) {
|
|
229
|
+
stage = "tls";
|
|
230
|
+
hint = "TLS failed. Check the certificate hostname and expiry. For a trusted company CA, try NODE_USE_SYSTEM_CA=1 on supported Node versions or set NODE_EXTRA_CA_CERTS to the company CA PEM file.";
|
|
231
|
+
} else if (has("ETIMEDOUT", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT")) hint = "Connection timed out. Check the VPN route, firewall and proxy.";
|
|
232
|
+
else if (has("ECONNREFUSED", "ECONNRESET", "UND_ERR_SOCKET", "EPIPE")) hint = "Connection refused or closed. Check that the server and any configured proxy are reachable.";
|
|
233
|
+
const method = init?.method ?? "GET";
|
|
234
|
+
const endpoint = target.origin + target.pathname;
|
|
235
|
+
const reason = [...codes].join(", ") || "no system error code reported";
|
|
236
|
+
return new CliError("E_NETWORK", `${method} ${endpoint} failed (${stage}: ${reason}). ${hint}`, {
|
|
237
|
+
method,
|
|
238
|
+
endpoint,
|
|
239
|
+
stage,
|
|
240
|
+
codes: [...codes],
|
|
241
|
+
hint,
|
|
242
|
+
nodeVersion: process.version,
|
|
243
|
+
proxyEnvironment: [
|
|
244
|
+
"HTTPS_PROXY",
|
|
245
|
+
"HTTP_PROXY",
|
|
246
|
+
"ALL_PROXY",
|
|
247
|
+
"https_proxy",
|
|
248
|
+
"http_proxy",
|
|
249
|
+
"all_proxy"
|
|
250
|
+
].filter((key) => Boolean(process.env[key]))
|
|
251
|
+
});
|
|
252
|
+
}
|
|
248
253
|
function configDir() {
|
|
249
254
|
const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
|
|
250
255
|
return path.join(base, "howone");
|
|
@@ -323,11 +328,29 @@ var HowoneApi = class HowoneApi {
|
|
|
323
328
|
return headers;
|
|
324
329
|
}
|
|
325
330
|
async request(method, apiPath, options = {}) {
|
|
326
|
-
const
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
+
const retries = options.retryNetwork ?? (/^(GET|HEAD)$/i.test(method) ? 2 : 0);
|
|
332
|
+
for (let attempt = 0;; attempt += 1) {
|
|
333
|
+
options.signal?.throwIfAborted();
|
|
334
|
+
try {
|
|
335
|
+
const response = await this.fetch(method, apiPath, options);
|
|
336
|
+
const text = await response.text().catch((error) => {
|
|
337
|
+
if (options.signal?.aborted) throw error;
|
|
338
|
+
throw networkError(this.url(apiPath, options.query), { method }, error);
|
|
339
|
+
});
|
|
340
|
+
const body = text ? parseJson(text) : null;
|
|
341
|
+
if (!response.ok) throw toApiError(response.status, body);
|
|
342
|
+
return body;
|
|
343
|
+
} catch (error) {
|
|
344
|
+
if (attempt >= retries || !isTransientNetworkError(error, options.signal)) {
|
|
345
|
+
if (attempt > 0 && error instanceof CliError && error.code === "E_NETWORK") throw new CliError(error.code, error.message, {
|
|
346
|
+
...error.details,
|
|
347
|
+
attempts: attempt + 1
|
|
348
|
+
});
|
|
349
|
+
throw error;
|
|
350
|
+
}
|
|
351
|
+
await delay(250 * 2 ** attempt);
|
|
352
|
+
}
|
|
353
|
+
}
|
|
331
354
|
}
|
|
332
355
|
/** 读 text/event-stream,每个事件回调一次;服务端发 `event: error` 时抛错。 */
|
|
333
356
|
async stream(method, apiPath, options, onEvent) {
|
|
@@ -365,11 +388,30 @@ var HowoneApi = class HowoneApi {
|
|
|
365
388
|
signal: options.signal
|
|
366
389
|
});
|
|
367
390
|
} catch (error) {
|
|
368
|
-
if (error instanceof CliError) throw error;
|
|
391
|
+
if (options.signal?.aborted || error instanceof CliError) throw error;
|
|
369
392
|
throw new CliError("E_NETWORK", `Cannot reach ${this.apiUrl}: ${error instanceof Error ? error.message : String(error)}`);
|
|
370
393
|
}
|
|
371
394
|
}
|
|
372
395
|
};
|
|
396
|
+
const TRANSIENT_NETWORK_CODES = new Set([
|
|
397
|
+
"ECONNRESET",
|
|
398
|
+
"ETIMEDOUT",
|
|
399
|
+
"UND_ERR_CONNECT_TIMEOUT",
|
|
400
|
+
"UND_ERR_HEADERS_TIMEOUT",
|
|
401
|
+
"UND_ERR_BODY_TIMEOUT",
|
|
402
|
+
"UND_ERR_SOCKET",
|
|
403
|
+
"EPIPE",
|
|
404
|
+
"EAI_AGAIN"
|
|
405
|
+
]);
|
|
406
|
+
function isTransientNetworkError(error, signal) {
|
|
407
|
+
if (signal?.aborted || !(error instanceof CliError) || error.code !== "E_NETWORK") return false;
|
|
408
|
+
if (error.details?.stage === "tls") return false;
|
|
409
|
+
const codes = error.details?.codes;
|
|
410
|
+
return Array.isArray(codes) && codes.some((code) => typeof code === "string" && TRANSIENT_NETWORK_CODES.has(code));
|
|
411
|
+
}
|
|
412
|
+
function delay(milliseconds) {
|
|
413
|
+
return new Promise((resolve) => setTimeout(resolve, milliseconds));
|
|
414
|
+
}
|
|
373
415
|
function parseSseChunk(chunk) {
|
|
374
416
|
let event = "message";
|
|
375
417
|
const data = [];
|
|
@@ -734,20 +776,26 @@ async function syncToSandbox(input) {
|
|
|
734
776
|
const actual = sha256(Buffer.from(write.contentBase64, "base64"));
|
|
735
777
|
if (actual !== write.sha256) write.sha256 = actual;
|
|
736
778
|
}
|
|
737
|
-
const result = await input.api.request("POST", `${appPath$1(input.app)}/sync`, {
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
779
|
+
const result = await input.api.request("POST", `${appPath$1(input.app)}/sync`, {
|
|
780
|
+
retryNetwork: 2,
|
|
781
|
+
body: {
|
|
782
|
+
clientId: input.lock.clientId,
|
|
783
|
+
fenceToken: input.lock.fenceToken,
|
|
784
|
+
writes,
|
|
785
|
+
deletes: index === batches.length - 1 ? remove : []
|
|
786
|
+
}
|
|
787
|
+
});
|
|
743
788
|
dependenciesChanged ||= result.dependenciesChanged;
|
|
744
789
|
}
|
|
745
|
-
if (!batches.length && remove.length) await input.api.request("POST", `${appPath$1(input.app)}/sync`, {
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
790
|
+
if (!batches.length && remove.length) await input.api.request("POST", `${appPath$1(input.app)}/sync`, {
|
|
791
|
+
retryNetwork: 2,
|
|
792
|
+
body: {
|
|
793
|
+
clientId: input.lock.clientId,
|
|
794
|
+
fenceToken: input.lock.fenceToken,
|
|
795
|
+
writes: [],
|
|
796
|
+
deletes: remove
|
|
797
|
+
}
|
|
798
|
+
});
|
|
751
799
|
const removed = new Set(remove);
|
|
752
800
|
const uploaded = new Map(plan.upload.map((file) => [file.path, file.sha256]));
|
|
753
801
|
const next = [...remote.filter((file) => !removed.has(file.path) && !uploaded.has(file.path)), ...plan.upload.map((file) => ({
|
|
@@ -1043,6 +1091,7 @@ async function scaffoldTemplate(root) {
|
|
|
1043
1091
|
recursive: true,
|
|
1044
1092
|
filter: (source) => !path.relative(template, source).split(path.sep).includes("node_modules")
|
|
1045
1093
|
});
|
|
1094
|
+
await rename(path.join(root, ".npmrc.template"), path.join(root, ".npmrc"));
|
|
1046
1095
|
try {
|
|
1047
1096
|
await rename(path.join(root, "gitignore"), path.join(root, ".gitignore"));
|
|
1048
1097
|
} catch (error) {
|
|
@@ -2297,10 +2346,13 @@ async function installTemplateDependencies(plan, json) {
|
|
|
2297
2346
|
maxBuffer: 10 * 1024 * 1024
|
|
2298
2347
|
});
|
|
2299
2348
|
} catch (error) {
|
|
2300
|
-
throw new CliError("E_DEP_INSTALL_FAILED", "Failed to install dependencies with bun.
|
|
2301
|
-
|
|
2302
|
-
|
|
2303
|
-
|
|
2349
|
+
throw new CliError("E_DEP_INSTALL_FAILED", "Failed to install dependencies with bun. Check the install log below. For @howone/sdk 404/401/403 errors, verify the private @howone registry and credentials in your user npm config, then run bun install again. Do not put tokens in the project .npmrc.", {
|
|
2350
|
+
...error && typeof error === "object" ? {
|
|
2351
|
+
stdout: "stdout" in error ? String(error.stdout ?? "") : void 0,
|
|
2352
|
+
stderr: "stderr" in error ? String(error.stderr ?? "") : void 0
|
|
2353
|
+
} : void 0,
|
|
2354
|
+
registryHint: "https://devrepo.devcloud.cn-east-3.huaweicloud.com/artgalaxy/api/npm/"
|
|
2355
|
+
});
|
|
2304
2356
|
}
|
|
2305
2357
|
};
|
|
2306
2358
|
if (json) {
|
|
@@ -2324,10 +2376,16 @@ async function performCreateTemplate(plan, howoneContext) {
|
|
|
2324
2376
|
return !path.relative(templateDir, source).split(path.sep).includes("node_modules");
|
|
2325
2377
|
}
|
|
2326
2378
|
});
|
|
2379
|
+
await materializeTemplateNpmrc(plan.targetDir);
|
|
2327
2380
|
await restoreGitignore(plan.targetDir);
|
|
2328
2381
|
await writeHowoneEnvFile(plan, howoneContext);
|
|
2329
2382
|
await assertTemplateCopied(plan);
|
|
2330
2383
|
}
|
|
2384
|
+
async function materializeTemplateNpmrc(targetDir) {
|
|
2385
|
+
const template = path.join(targetDir, ".npmrc.template");
|
|
2386
|
+
if (!await pathExists(template)) return;
|
|
2387
|
+
await rename(template, path.join(targetDir, ".npmrc"));
|
|
2388
|
+
}
|
|
2331
2389
|
function normalizeHowoneEnv(value) {
|
|
2332
2390
|
const normalized = value?.trim().toLowerCase();
|
|
2333
2391
|
if (!normalized) return "dev";
|
package/package.json
CHANGED
|
@@ -105,3 +105,5 @@ Only after the user explicitly agreed, having seen the preview.
|
|
|
105
105
|
| `E_BUILD_FAILED` | build failed | read `details.build.log`, fix, push again |
|
|
106
106
|
| `E_SEAL_FAILED` | version rejected before build (functions, entities) | read `details`, fix, push again |
|
|
107
107
|
| `E_NOT_FOUND` | unknown app / version | re-check with `howone apps list` |
|
|
108
|
+
| `E_DEP_INSTALL_FAILED` | template dependency install failed | check the private `@howone` registry credentials in the user's npm config, then run `bun install` again; do not change the SDK version to a public npm version |
|
|
109
|
+
| `E_NETWORK` | transport failed | the CLI retries transient read/sync failures at most twice; if it still fails, inspect `details.codes`, proxy and VPN routing. `--insecure` only affects API TLS verification. Keep the existing App and query its state before repeating a mutation whose response was lost |
|
|
@@ -49,6 +49,10 @@ howone workflows update <capabilityName> --prompt "<change>" --json
|
|
|
49
49
|
howone push -m "..." --json # makes contracts + code a version
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
+
If a workflow needs custom project Functions, read `coding/03-ai-capabilities/06-functions.md`.
|
|
53
|
+
Write and push `functions/<name>/` before workflow create/update; those commands register remote
|
|
54
|
+
sandbox functions and pass the catalog to EAX. Plain AI generation does not require Functions.
|
|
55
|
+
|
|
52
56
|
1. Design the contract following `coding/03-ai-capabilities/01-ai-capability-architecture.md`
|
|
53
57
|
and `02-workflow-contract-rules.md`; the patch format is `{ "operations": [...] }` with
|
|
54
58
|
`create_capability` / `update_capability` / `delete_capability`.
|
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
# Functions and data
|
|
2
2
|
|
|
3
3
|
How to write functions and entities is in `coding/03-ai-capabilities/06-functions.md` and
|
|
4
|
-
`coding/02-entity-schema/`.
|
|
4
|
+
`coding/02-entity-schema/`. Read the functions reference before writing a function; it covers
|
|
5
|
+
the spec, runtime APIs, and EAX handoff. This page covers CLI commands.
|
|
5
6
|
|
|
6
7
|
## Functions (`functions/<name>/` in the app)
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
Upload functions with `howone push`, then check `fn list` and `fn test`. Push local functions
|
|
10
|
+
before workflow create/update: generation reads the remote sandbox and does not upload local
|
|
11
|
+
files. A generated AI workflow alone is not a custom Function. Around that:
|
|
9
12
|
|
|
10
13
|
```bash
|
|
11
14
|
howone fn list --json # functions of the latest version
|
package/skills/howone/SKILL.md
CHANGED
|
@@ -13,6 +13,14 @@ human-readable output.
|
|
|
13
13
|
If `howone` is not on PATH, use `npx --yes @howone/agent-cli@<version>` with the version in
|
|
14
14
|
`.howone-cli.json` next to this file.
|
|
15
15
|
|
|
16
|
+
Before starting an app task, compare `howone --version` with `.howone-cli.json` when present.
|
|
17
|
+
If they differ, the normal `howone whoami --json` check refreshes previously installed Skills to
|
|
18
|
+
match that CLI. Read the marker again afterward. When the version differs from the instructions
|
|
19
|
+
already loaded in this session, reread this file and the relevant reference from disk. Background
|
|
20
|
+
CLI updates take effect on the next invocation; check again before resuming work after an update.
|
|
21
|
+
Do not assume an open session automatically reloads Skill files, or that version output alone
|
|
22
|
+
checks npm for updates.
|
|
23
|
+
|
|
16
24
|
## Pick the track
|
|
17
25
|
|
|
18
26
|
| The user wants to… | Read |
|
package/templates/vite/.howone/skills/howone/03-ai-capabilities/01-ai-capability-architecture.md
CHANGED
|
@@ -28,6 +28,10 @@ Do not collapse these layers. The common mistakes are:
|
|
|
28
28
|
- treating workflow `outputSchema` as a database schema;
|
|
29
29
|
- faking unsupported AI with static frontend data.
|
|
30
30
|
|
|
31
|
+
For custom server-side functions that a workflow should call, read `06-functions.md` for
|
|
32
|
+
the Function spec, isolated runtime and upload/registration/EAX catalog handoff. AI contracts
|
|
33
|
+
and project Functions are separate artifacts.
|
|
34
|
+
|
|
31
35
|
## Source Of Truth
|
|
32
36
|
|
|
33
37
|
```text
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Project Functions
|
|
2
|
+
|
|
3
|
+
Use this for custom server-side logic or reusable functions an EAX workflow should call.
|
|
4
|
+
Ordinary React helpers belong in `src/`. Generating an AI workflow does not itself create a
|
|
5
|
+
project Function. Use Functions when custom computation, an external API or a server-side
|
|
6
|
+
data operation is needed; ordinary AI generation can use the capability/workflow flow alone.
|
|
7
|
+
|
|
8
|
+
## Files and contract
|
|
9
|
+
|
|
10
|
+
Create `functions/<name>/function.json` and `functions/<name>/index.ts` in the app root.
|
|
11
|
+
Optional helpers go under that function directory, e.g. `lib/`. Optional `index.test.ts` uses
|
|
12
|
+
a fake context locally and is excluded from the runtime bundle.
|
|
13
|
+
|
|
14
|
+
Function specs use **input/output**, not AI contracts' `inputSchema/outputSchema`.
|
|
15
|
+
Name must match the directory and `^[a-z][a-z0-9-]{1,62}$`. Both schemas must be objects with
|
|
16
|
+
nonempty `properties`. Minimal `functions/normalize-text/function.json`:
|
|
17
|
+
|
|
18
|
+
```json
|
|
19
|
+
{
|
|
20
|
+
"name": "normalize-text",
|
|
21
|
+
"description": "Trim text and collapse consecutive whitespace.",
|
|
22
|
+
"input": {
|
|
23
|
+
"type": "object",
|
|
24
|
+
"properties": { "text": { "type": "string" } },
|
|
25
|
+
"required": ["text"],
|
|
26
|
+
"additionalProperties": false
|
|
27
|
+
},
|
|
28
|
+
"output": {
|
|
29
|
+
"type": "object",
|
|
30
|
+
"properties": { "text": { "type": "string" } },
|
|
31
|
+
"required": ["text"],
|
|
32
|
+
"additionalProperties": false
|
|
33
|
+
},
|
|
34
|
+
"dependencies": [],
|
|
35
|
+
"capabilities": [],
|
|
36
|
+
"limits": { "timeoutMs": 5000, "memoryMb": 64 }
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`index.ts` exports the handler as default. Return a JSON-serializable object matching output:
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
export default async function (input: { text: string }) {
|
|
44
|
+
return { text: input.text.trim().replace(/\s+/g, " ") }
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Functions run in an isolated runtime, not a Node server. No `process`, `require`, global
|
|
49
|
+
`fetch`, timers, filesystem or environment variables. Imports may reference files inside
|
|
50
|
+
this function or platform-provided `zod`, `lodash-es`, `dayjs`. Installing an app npm
|
|
51
|
+
dependency does not install it in the Function runtime. Optional
|
|
52
|
+
`import type { FunctionContext } from "@howone/functions"` is a platform build-time type
|
|
53
|
+
import, not a runtime dependency to install from npm. Pure functions can omit `ctx`.
|
|
54
|
+
|
|
55
|
+
## Context and declarations
|
|
56
|
+
|
|
57
|
+
The handler's second argument `ctx` provides logging, run metadata, deadline, idempotency key
|
|
58
|
+
and declared capabilities. Declare only what the function needs:
|
|
59
|
+
|
|
60
|
+
| Need | function.json declaration | Handler API |
|
|
61
|
+
|---|---|---|
|
|
62
|
+
| Another project Function | `capabilities: ["functions"]`, `dependencies: ["normalize-text"]` | `await ctx.functions.call("normalize-text", { text })` |
|
|
63
|
+
| External HTTPS service | `capabilities: ["connections"]`, named `connections` | `await ctx.connections.news.fetch("/items", { method: "GET" })` |
|
|
64
|
+
| App entities | `capabilities: ["data"]`, `data: { "entities": { "Article": ["read", "create"] } }` | `ctx.data.list/get/create/update/delete` |
|
|
65
|
+
| EAX host tool | `capabilities: ["tools"]`, `tools: ["<available-tool-name>"]` | `await ctx.tools.call(name, input)` |
|
|
66
|
+
| EAX host LLM | `capabilities: ["llm"]` | `await ctx.llm.complete({ prompt, json: true })` |
|
|
67
|
+
|
|
68
|
+
Use tool names available in the target environment; declarations do not create tools. Tools
|
|
69
|
+
and LLM require the EAX callback execution channel; ordinary HTTP invocation cannot supply
|
|
70
|
+
them. Optional `budgets: { "llmUsd": 0.2, "toolCalls": 10 }` bounds the entry function's call
|
|
71
|
+
tree. Function dependencies are pinned at registration; do not import sibling functions.
|
|
72
|
+
|
|
73
|
+
For data, first create entities through the schema flow and sync the database manifest.
|
|
74
|
+
Names and operations must match `data.entities` and the manifest. Backend enforces caller
|
|
75
|
+
permissions; the platform supplies caller identity. Never embed database credentials or
|
|
76
|
+
caller tokens. Schema declarations in function.json do not create entities. Use SDK/UI
|
|
77
|
+
persistence for ordinary AI output; choose a data Function for requested server-side logic.
|
|
78
|
+
|
|
79
|
+
Example external connection fragment (merge into the spec):
|
|
80
|
+
|
|
81
|
+
```json
|
|
82
|
+
{
|
|
83
|
+
"capabilities": ["connections"],
|
|
84
|
+
"connections": {
|
|
85
|
+
"news": {
|
|
86
|
+
"baseUrl": "https://api.example.com/v1",
|
|
87
|
+
"auth": { "type": "bearer", "secret": "NEWS_API_TOKEN" }
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The host injects the named project secret; store its value through CLI secrets commands,
|
|
94
|
+
never in code, specs or fixtures. The fetch result is `{ status, headers, body, json? }`,
|
|
95
|
+
not a browser Response. Additional hosts must be declared in `connections.news.hosts`.
|
|
96
|
+
Connections require HTTPS and reject private/loopback/metadata addresses.
|
|
97
|
+
|
|
98
|
+
Optional `http: { "method": "POST", "path": "text/normalize", "auth": ["user"] }` exposes
|
|
99
|
+
a route through Backend at `/api/apps/<appId>/fn/<path>` after publication. `apiKey` is also
|
|
100
|
+
a supported auth mode. Routes follow the published Revision; push/test does not publish.
|
|
101
|
+
Functions requiring tools/LLM cannot be exposed as ordinary HTTP endpoints.
|
|
102
|
+
|
|
103
|
+
## CLI upload and EAX handoff
|
|
104
|
+
|
|
105
|
+
Run from the bound app directory using its login/API origin:
|
|
106
|
+
|
|
107
|
+
1. Write and check the function locally. Apply/sync required entity schemas first. Upload
|
|
108
|
+
sources with `howone push -m "add project function" --json`.
|
|
109
|
+
2. Inspect `howone fn list --json` and
|
|
110
|
+
`howone fn test normalize-text --input '{"text":" hello world "}' --json`.
|
|
111
|
+
App build success alone does not prove Function registration succeeded.
|
|
112
|
+
3. For an AI workflow, apply its capability contract and run `howone ai sync --json` using
|
|
113
|
+
the workflow guide. Describe the intended Function usage in the capability description.
|
|
114
|
+
4. Run `howone workflows create <capabilityName> --json`, or update an existing workflow
|
|
115
|
+
using `howone workflows update <capabilityName> --prompt "<change and function usage>" --json`.
|
|
116
|
+
Submission reads the **remote sandbox**, registers its functions with Function Service
|
|
117
|
+
and sends names, schemas and immutable versions as `functionCatalog` to EAX. It does
|
|
118
|
+
not upload local sources. Push changed Functions before create/update.
|
|
119
|
+
5. Keep the job ID. Use `howone workflows status <jobId> --app <app-short-id> --wait --json`.
|
|
120
|
+
On timeout, check the same job rather than submitting again. Once status is `completed`,
|
|
121
|
+
sync AI artifacts, read the manifest, bind the SDK and push.
|
|
122
|
+
|
|
123
|
+
A catalog entry makes a Function available for authoring; it does not prove the generated
|
|
124
|
+
workflow uses it. Inspect workflow details when available and verify behavior before claiming
|
|
125
|
+
integration works. Updating Function source does not automatically rebind a pinned workflow;
|
|
126
|
+
submit the intended workflow update.
|
|
127
|
+
|
|
128
|
+
Registration errors include build/schema details. Fix the named file, push, and retry the
|
|
129
|
+
failed operation. Missing `FUNCTION_SERVICE_URL`/`FUNCTION_SERVICE_TOKEN` is a platform
|
|
130
|
+
configuration problem; do not ask users to invent service credentials or bypass registration.
|
|
131
|
+
|
|
132
|
+
## Platform test mode
|
|
133
|
+
|
|
134
|
+
`fn test` runs the latest **pushed** version: real data reads, simulated writes and recorded
|
|
135
|
+
fixtures for external requests/tools/LLM. Missing fixtures fail with
|
|
136
|
+
`FUNCTION_FIXTURE_MISSING`; do not replace production logic with mocks to pass. Example
|
|
137
|
+
`functions/<name>/fixtures.json` for the connection above:
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"connections": {
|
|
142
|
+
"news": [{ "method": "GET", "path": "/items", "json": { "items": [] } }]
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Other fixture forms: `tools: { "<tool-name>": <recorded-result> }` and
|
|
148
|
+
`llm: [{ "match": "optional prompt substring", "text": "recorded reply" }]`.
|
|
149
|
+
Push fixture changes before retrying. Report fixture tests separately from live integration
|
|
150
|
+
runs; perform live calls only within the user's requested scope.
|
package/templates/vite/AGENTS.md
CHANGED
|
@@ -9,6 +9,7 @@ Read this file once when entering the project, follow it during implementation,
|
|
|
9
9
|
- Package manager: `bun`
|
|
10
10
|
- Common commands: `bun run dev`, `bun run typecheck`, `bun run build`
|
|
11
11
|
- The scaffold normally installs dependencies during `howone init app`. If `node_modules` is missing, run `bun install` before validation instead of treating missing binaries as code failures.
|
|
12
|
+
- `@howone/sdk` uses the private registry configured in the project `.npmrc`. If it returns 404/401/403, check that registry and user-level credentials; do not downgrade to a public npm version or add credentials to project files.
|
|
12
13
|
- Default stack: React, Vite, TypeScript, Tailwind CSS, shadcn/ui-style components, `@howone/sdk`
|
|
13
14
|
|
|
14
15
|
## Source of Truth
|