@howone/agent-cli 0.5.3 → 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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howone/agent-cli",
3
- "version": "0.5.3",
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",
@@ -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/`. This page is only the CLI side.
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
- Functions are deployed with the app by `howone push`. Around that:
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
@@ -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.