@howone/agent-cli 0.5.2 → 0.5.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 +18 -0
- package/bin/index.mjs +193 -7
- package/package.json +2 -1
- package/skills/howone/03-workflows.md +4 -0
- package/skills/howone/04-functions-and-data.md +5 -2
- 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/README.md
CHANGED
|
@@ -43,3 +43,21 @@ npm install -g @howone/agent-cli
|
|
|
43
43
|
已有同路径 HowOne Skill 会被更新。其他 Skill 不受影响。
|
|
44
44
|
禁用安装脚本(如 --ignore-scripts)的环境需手动运行 howone setup --target codex。
|
|
45
45
|
Skill 安装失败不会阻止 CLI 安装,使用 setup 可重试。
|
|
46
|
+
|
|
47
|
+
## 自动更新
|
|
48
|
+
|
|
49
|
+
npm 全局安装的 CLI 在命令成功结束后,后台每天检查一次 npm `latest` 稳定版。
|
|
50
|
+
有新版时,自动更新同一安装位置的 `@howone/agent-cli`,并通过安装脚本更新 Skill。
|
|
51
|
+
本次命令继续使用原版本,下次启动使用新版;登录凭证和 App 文件不变。
|
|
52
|
+
检查和更新失败不会阻断命令,也不会污染 `--json` 输出。
|
|
53
|
+
|
|
54
|
+
设置 `HOWONE_AUTO_UPDATE=0` 可关闭自动更新。CI、源码开发、npx 临时运行和无写权限的
|
|
55
|
+
系统级安装跳过自动更新;不会请求 sudo,也不会更改 npm 的全局 registry 配置。
|
|
56
|
+
此功能需先手动安装包含它的新版 CLI,旧版不会自行获得更新能力。
|
|
57
|
+
|
|
58
|
+
## 临时跳过 API 证书校验
|
|
59
|
+
|
|
60
|
+
`howone login --api-url https://isoeax.howone.dev --insecure` 显式跳过本次命令的
|
|
61
|
+
目标 API 证书校验,并在 stderr 显示警告。该设置不保存,后续命令需要再次指定。
|
|
62
|
+
默认仍校验证书;优先修复公司 CA 或服务端证书链。该参数不会影响 npm 自动更新,
|
|
63
|
+
不允许把跳过校验的请求重定向到其他地址,也不会修改系统或 Node 的全局 TLS 设置。
|
package/bin/index.mjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import { createRequire } from "node:module";
|
|
3
3
|
import { execFile, spawn } from "node:child_process";
|
|
4
|
-
import { appendFile, chmod, cp, lstat, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
|
|
4
|
+
import { access, appendFile, chmod, cp, lstat, mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
|
|
5
5
|
import path from "node:path";
|
|
6
6
|
import { fileURLToPath } from "node:url";
|
|
7
7
|
import { promisify } from "node:util";
|
|
@@ -11,9 +11,155 @@ import { copy, emptyDir, ensureDir, pathExists } from "fs-extra/esm";
|
|
|
11
11
|
import pc from "picocolors";
|
|
12
12
|
import validatePackageName from "validate-npm-package-name";
|
|
13
13
|
import yargsParser from "yargs-parser";
|
|
14
|
-
import { existsSync, watch } from "node:fs";
|
|
15
|
-
import os from "node:os";
|
|
16
14
|
import { createHash, randomUUID } from "node:crypto";
|
|
15
|
+
import { constants, existsSync, watch } from "node:fs";
|
|
16
|
+
import os from "node:os";
|
|
17
|
+
//#region src/auto-update.ts
|
|
18
|
+
const execFileAsync$2 = promisify(execFile);
|
|
19
|
+
const PACKAGE = "@howone/agent-cli";
|
|
20
|
+
const REGISTRY = "https://registry.npmjs.org/";
|
|
21
|
+
const DAY = 1440 * 60 * 1e3;
|
|
22
|
+
const LOCK_TTL = 600 * 1e3;
|
|
23
|
+
const WORKER_ARG = "--internal-auto-update";
|
|
24
|
+
function globalInstallPrefix(root, platform = process.platform) {
|
|
25
|
+
if (path.basename(root) !== "agent-cli" || path.basename(path.dirname(root)) !== "@howone") return null;
|
|
26
|
+
const modules = path.dirname(path.dirname(root));
|
|
27
|
+
if (path.basename(modules) !== "node_modules") return null;
|
|
28
|
+
const parent = path.dirname(modules);
|
|
29
|
+
if (platform === "win32") {
|
|
30
|
+
if (path.basename(parent) === "_npx" || parent.includes(`${path.sep}_npx${path.sep}`)) return null;
|
|
31
|
+
return parent;
|
|
32
|
+
}
|
|
33
|
+
return path.basename(parent) === "lib" ? path.dirname(parent) : null;
|
|
34
|
+
}
|
|
35
|
+
function autoUpdateEnabled(env = process.env) {
|
|
36
|
+
return env.HOWONE_AUTO_UPDATE !== "0" && !env.CI && !env.npm_lifecycle_event && !env.npm_execpath?.includes("npx");
|
|
37
|
+
}
|
|
38
|
+
/** Only a completed command starts the detached updater; stdout/JSON stays untouched. */
|
|
39
|
+
function scheduleAutoUpdate(root) {
|
|
40
|
+
if (!autoUpdateEnabled() || !globalInstallPrefix(root)) return;
|
|
41
|
+
process.once("exit", (code) => {
|
|
42
|
+
if (code !== 0) return;
|
|
43
|
+
try {
|
|
44
|
+
const child = spawn(process.execPath, [path.join(root, "bin", "index.mjs"), WORKER_ARG], {
|
|
45
|
+
detached: true,
|
|
46
|
+
stdio: "ignore",
|
|
47
|
+
windowsHide: true
|
|
48
|
+
});
|
|
49
|
+
child.on("error", () => {});
|
|
50
|
+
child.unref();
|
|
51
|
+
} catch {}
|
|
52
|
+
});
|
|
53
|
+
}
|
|
54
|
+
function newerStable(latest, current) {
|
|
55
|
+
if (!/^\d+\.\d+\.\d+$/.test(latest) || !/^\d+\.\d+\.\d+$/.test(current)) return false;
|
|
56
|
+
const a = latest.split(".").map(Number);
|
|
57
|
+
const b = current.split(".").map(Number);
|
|
58
|
+
for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return (a[i] ?? 0) > (b[i] ?? 0);
|
|
59
|
+
return false;
|
|
60
|
+
}
|
|
61
|
+
async function npmCommand() {
|
|
62
|
+
if (process.platform === "win32") {
|
|
63
|
+
const candidates = [path.join(path.dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js"), ...(process.env.PATH ?? "").split(path.delimiter).map((dir) => path.join(dir, "node_modules", "npm", "bin", "npm-cli.js"))];
|
|
64
|
+
for (const candidate of candidates) if (await stat(candidate).then((s) => s.isFile()).catch(() => false)) return {
|
|
65
|
+
executable: process.execPath,
|
|
66
|
+
args: [candidate]
|
|
67
|
+
};
|
|
68
|
+
throw new Error("npm is not available");
|
|
69
|
+
}
|
|
70
|
+
return {
|
|
71
|
+
executable: "npm",
|
|
72
|
+
args: []
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
async function runAutoUpdate(options) {
|
|
76
|
+
const prefix = globalInstallPrefix(options.root);
|
|
77
|
+
if (!prefix || !autoUpdateEnabled(options.env)) return;
|
|
78
|
+
if (await realpath(options.root) !== path.resolve(options.root)) return;
|
|
79
|
+
const launcher = process.platform === "win32" ? path.join(prefix, "howone.cmd") : path.join(prefix, "bin", "howone");
|
|
80
|
+
if (process.platform === "win32") {
|
|
81
|
+
if (!(await stat(launcher)).isFile()) return;
|
|
82
|
+
} else if (await realpath(launcher) !== path.join(options.root, "bin", "index.mjs")) return;
|
|
83
|
+
await Promise.all([
|
|
84
|
+
options.root,
|
|
85
|
+
path.dirname(path.dirname(options.root)),
|
|
86
|
+
process.platform === "win32" ? prefix : path.join(prefix, "bin")
|
|
87
|
+
].map((dir) => access(dir, constants.W_OK)));
|
|
88
|
+
const key = createHash("sha256").update(prefix).digest("hex").slice(0, 16);
|
|
89
|
+
const cacheDir = options.cacheDir ?? path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "howone", "updates");
|
|
90
|
+
await mkdir(cacheDir, {
|
|
91
|
+
recursive: true,
|
|
92
|
+
mode: 448
|
|
93
|
+
});
|
|
94
|
+
const stateFile = path.join(cacheDir, `${key}.json`);
|
|
95
|
+
const lock = path.join(cacheDir, `${key}.lock`);
|
|
96
|
+
const now = options.now ?? Date.now();
|
|
97
|
+
const lockStat = await stat(lock).catch(() => null);
|
|
98
|
+
if (lockStat && now - lockStat.mtimeMs > LOCK_TTL) await rm(lock, {
|
|
99
|
+
recursive: true,
|
|
100
|
+
force: true
|
|
101
|
+
});
|
|
102
|
+
try {
|
|
103
|
+
await mkdir(lock);
|
|
104
|
+
} catch (error) {
|
|
105
|
+
if (error.code === "EEXIST") return;
|
|
106
|
+
throw error;
|
|
107
|
+
}
|
|
108
|
+
try {
|
|
109
|
+
const previous = await readFile(stateFile, "utf8").then(JSON.parse).catch(() => null);
|
|
110
|
+
if (previous?.checkedAt && now - previous.checkedAt < DAY) return;
|
|
111
|
+
await writeFile(stateFile, JSON.stringify({ checkedAt: now }), { mode: 384 });
|
|
112
|
+
const npm = options.runNpm ? null : await npmCommand();
|
|
113
|
+
const runNpm = options.runNpm ?? (async (args) => {
|
|
114
|
+
const { stdout } = await execFileAsync$2(npm.executable, [...npm.args, ...args], {
|
|
115
|
+
timeout: args[0] === "view" ? 2e4 : 18e4,
|
|
116
|
+
maxBuffer: 1024 * 1024,
|
|
117
|
+
windowsHide: true,
|
|
118
|
+
env: {
|
|
119
|
+
...process.env,
|
|
120
|
+
HOWONE_AUTO_UPDATE: "0"
|
|
121
|
+
}
|
|
122
|
+
});
|
|
123
|
+
return stdout;
|
|
124
|
+
});
|
|
125
|
+
const registryArgs = [`--registry=${REGISTRY}`, `--@howone:registry=${REGISTRY}`];
|
|
126
|
+
const latest = JSON.parse(await runNpm([
|
|
127
|
+
"view",
|
|
128
|
+
`${PACKAGE}@latest`,
|
|
129
|
+
"version",
|
|
130
|
+
"--json",
|
|
131
|
+
...registryArgs,
|
|
132
|
+
"--fetch-retries=0",
|
|
133
|
+
"--fetch-timeout=15000"
|
|
134
|
+
]));
|
|
135
|
+
if (typeof latest !== "string" || !newerStable(latest, options.currentVersion)) return;
|
|
136
|
+
await runNpm([
|
|
137
|
+
"install",
|
|
138
|
+
"--global",
|
|
139
|
+
"--prefix",
|
|
140
|
+
prefix,
|
|
141
|
+
`${PACKAGE}@${latest}`,
|
|
142
|
+
...registryArgs,
|
|
143
|
+
"--engine-strict",
|
|
144
|
+
"--ignore-scripts=false",
|
|
145
|
+
"--no-audit",
|
|
146
|
+
"--no-fund",
|
|
147
|
+
"--fetch-retries=0",
|
|
148
|
+
"--fetch-timeout=30000"
|
|
149
|
+
]);
|
|
150
|
+
await writeFile(stateFile, JSON.stringify({
|
|
151
|
+
checkedAt: now,
|
|
152
|
+
updatedTo: latest
|
|
153
|
+
}), { mode: 384 });
|
|
154
|
+
} finally {
|
|
155
|
+
await rm(lock, {
|
|
156
|
+
recursive: true,
|
|
157
|
+
force: true
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
const isAutoUpdateWorker = () => process.argv[2] === WORKER_ARG;
|
|
162
|
+
//#endregion
|
|
17
163
|
//#region src/errors.ts
|
|
18
164
|
var CliError = class extends Error {
|
|
19
165
|
constructor(code, message, details) {
|
|
@@ -25,10 +171,34 @@ var CliError = class extends Error {
|
|
|
25
171
|
};
|
|
26
172
|
//#endregion
|
|
27
173
|
//#region src/network.ts
|
|
174
|
+
let insecureOrigin;
|
|
175
|
+
let insecureDispatcher;
|
|
176
|
+
/** Explicit command-local exception; never changes Node's global TLS settings. */
|
|
177
|
+
function configureInsecureTls(apiUrl) {
|
|
178
|
+
insecureOrigin = new URL(apiUrl).origin;
|
|
179
|
+
}
|
|
28
180
|
async function networkFetch(url, init) {
|
|
29
181
|
const target = new URL(url);
|
|
30
182
|
if (!["http:", "https:"].includes(target.protocol) || target.username || target.password) throw new CliError("E_BAD_URL", "Use an HTTP(S) API URL without embedded credentials.");
|
|
31
183
|
try {
|
|
184
|
+
if (target.protocol === "https:" && target.origin === insecureOrigin) {
|
|
185
|
+
const { Agent, EnvHttpProxyAgent, fetch: insecureFetch } = await import("undici");
|
|
186
|
+
const hasProxy = [
|
|
187
|
+
"http_proxy",
|
|
188
|
+
"HTTP_PROXY",
|
|
189
|
+
"https_proxy",
|
|
190
|
+
"HTTPS_PROXY"
|
|
191
|
+
].some((key) => process.env[key]);
|
|
192
|
+
insecureDispatcher ??= hasProxy ? new EnvHttpProxyAgent({
|
|
193
|
+
connect: { rejectUnauthorized: false },
|
|
194
|
+
requestTls: { rejectUnauthorized: false }
|
|
195
|
+
}) : new Agent({ connect: { rejectUnauthorized: false } });
|
|
196
|
+
return await insecureFetch(target, {
|
|
197
|
+
...init,
|
|
198
|
+
redirect: "error",
|
|
199
|
+
dispatcher: insecureDispatcher
|
|
200
|
+
});
|
|
201
|
+
}
|
|
32
202
|
return await fetch(target, init);
|
|
33
203
|
} catch (error) {
|
|
34
204
|
if (init?.signal?.aborted) throw error;
|
|
@@ -1501,11 +1671,24 @@ const execFileAsync = promisify(execFile);
|
|
|
1501
1671
|
const DEFAULT_PROJECT_NAME = "howone-app";
|
|
1502
1672
|
const TEMPLATES = ["vite"];
|
|
1503
1673
|
const TEMPLATE_ALIASES = { vite: "vite" };
|
|
1504
|
-
|
|
1505
|
-
|
|
1506
|
-
|
|
1674
|
+
if (isAutoUpdateWorker()) runAutoUpdate({
|
|
1675
|
+
root: path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."),
|
|
1676
|
+
currentVersion: packageJson.version
|
|
1677
|
+
}).catch(() => {});
|
|
1678
|
+
else {
|
|
1679
|
+
scheduleAutoUpdate(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
|
|
1680
|
+
main().catch((error) => {
|
|
1681
|
+
handleFatalError(error, process.argv.includes("--json"));
|
|
1682
|
+
});
|
|
1683
|
+
}
|
|
1507
1684
|
async function main() {
|
|
1508
1685
|
const command = parseCommand(process.argv.slice(2));
|
|
1686
|
+
if (command.options.insecure && !command.options.help && !command.options.version) {
|
|
1687
|
+
const destination = command.options.apiUrl?.trim();
|
|
1688
|
+
const connection = await resolveConnection({ apiUrl: destination && !destination.includes("://") ? `https://${destination}` : destination });
|
|
1689
|
+
configureInsecureTls(connection.apiUrl);
|
|
1690
|
+
console.error(`Warning: --insecure disables TLS certificate verification for ${new URL(connection.apiUrl).origin} for this command only.`);
|
|
1691
|
+
}
|
|
1509
1692
|
if (command.options.version) {
|
|
1510
1693
|
console.log(packageJson.version);
|
|
1511
1694
|
return;
|
|
@@ -1613,7 +1796,8 @@ function parseCommand(args) {
|
|
|
1613
1796
|
"skill",
|
|
1614
1797
|
"browser",
|
|
1615
1798
|
"fresh",
|
|
1616
|
-
"wait"
|
|
1799
|
+
"wait",
|
|
1800
|
+
"insecure"
|
|
1617
1801
|
],
|
|
1618
1802
|
default: {
|
|
1619
1803
|
build: true,
|
|
@@ -1663,6 +1847,7 @@ function parseCommand(args) {
|
|
|
1663
1847
|
prompt: typeof parsed.prompt === "string" ? parsed.prompt : void 0,
|
|
1664
1848
|
region: typeof parsed.region === "string" ? parsed.region : void 0,
|
|
1665
1849
|
apiUrl: typeof parsed["api-url"] === "string" ? parsed["api-url"] : void 0,
|
|
1850
|
+
insecure: Boolean(parsed.insecure),
|
|
1666
1851
|
token: typeof parsed.token === "string" ? parsed.token : void 0,
|
|
1667
1852
|
stream: Boolean(parsed.stream),
|
|
1668
1853
|
status: typeof parsed.status === "string" ? parsed.status : void 0,
|
|
@@ -2307,6 +2492,7 @@ function printRootHelp() {
|
|
|
2307
2492
|
formatCommand("-v, --version", "Show version"),
|
|
2308
2493
|
formatCommand("--app <app>", "Which app (default: the pulled directory you are in)"),
|
|
2309
2494
|
formatCommand("--json", "Machine-readable output (for agents and CI)"),
|
|
2495
|
+
formatCommand("--insecure", "Skip API TLS certificate verification for this command only"),
|
|
2310
2496
|
"",
|
|
2311
2497
|
pc.bold("Examples"),
|
|
2312
2498
|
` ${pc.cyan("howone login")}`,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@howone/agent-cli",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.4",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "HowOne CLI and agent skill installer for Codex and Claude.",
|
|
6
6
|
"type": "module",
|
|
@@ -36,6 +36,7 @@
|
|
|
36
36
|
"@clack/prompts": "^1.3.0",
|
|
37
37
|
"fs-extra": "^11.3.4",
|
|
38
38
|
"picocolors": "^1.1.1",
|
|
39
|
+
"undici": "^6.27.0",
|
|
39
40
|
"validate-npm-package-name": "^7.0.2",
|
|
40
41
|
"yargs-parser": "^22.0.0"
|
|
41
42
|
},
|
|
@@ -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/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.
|