foldkit-agent-native 0.2.0 → 0.3.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.
- package/README.md +231 -77
- package/dist/index.d.mts +13 -7
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +1 -26
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,12 +1,57 @@
|
|
|
1
1
|
# `foldkit-agent-native`
|
|
2
2
|
|
|
3
|
-
Compiles a [`foldkit-agent`](../agent) contract into Agent Native
|
|
3
|
+
Compiles a [`foldkit-agent`](../agent) contract into [Agent Native](https://github.com/BuilderIO/agent-native)
|
|
4
|
+
actions.
|
|
4
5
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
Use it when the host application already uses Agent Native's action registry and
|
|
7
|
+
you want those actions to be the **same capabilities** your Foldkit application
|
|
8
|
+
already exposes. The generated action delegates validation, availability,
|
|
9
|
+
authorization, dispatch, and completion back to a bound `AgentRuntime`; it does
|
|
10
|
+
not reimplement application behavior.
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
```text
|
|
13
|
+
Foldkit application
|
|
14
|
+
|
|
|
15
|
+
v
|
|
16
|
+
AssistantAgent protocol-neutral contract
|
|
17
|
+
|
|
|
18
|
+
| AgentBuilder.bind(...)
|
|
19
|
+
v
|
|
20
|
+
AgentRuntime live Model + dispatch + policy
|
|
21
|
+
^
|
|
22
|
+
|
|
|
23
|
+
resolveRuntime(ctx)
|
|
24
|
+
|
|
|
25
|
+
foldkit-agent-native adapter
|
|
26
|
+
|
|
|
27
|
+
v
|
|
28
|
+
Agent Native action registry
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Application behavior still ends in the existing Foldkit Message and `update`.
|
|
32
|
+
This package is an adapter, not a second agent architecture.
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pnpm add foldkit-agent foldkit-agent-native @agent-native/core
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`foldkit`, `effect`, `foldkit-agent`, and `@agent-native/core` are peer
|
|
41
|
+
dependencies.
|
|
42
|
+
|
|
43
|
+
## Sixty seconds: generate actions
|
|
44
|
+
|
|
45
|
+
Assume the application already declared a protocol-neutral contract:
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
const AgentBuilder = Agent.forApplication(App).withPrincipal<Principal>()
|
|
49
|
+
const AssistantAgent = AgentBuilder.make({ ... })
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Agent Native needs a static action registry, but the live Model and principal
|
|
53
|
+
belong to the caller. Register the contract once and resolve the bound runtime
|
|
54
|
+
per invocation:
|
|
10
55
|
|
|
11
56
|
```ts
|
|
12
57
|
import { AgentNative } from 'foldkit-agent-native'
|
|
@@ -14,106 +59,215 @@ import { registerPackageActions } from '@agent-native/core/server'
|
|
|
14
59
|
|
|
15
60
|
registerPackageActions(
|
|
16
61
|
AgentNative.actions({
|
|
17
|
-
definition:
|
|
18
|
-
resolveRuntime:
|
|
62
|
+
definition: AssistantAgent,
|
|
63
|
+
resolveRuntime: context => runtimeFor(context),
|
|
19
64
|
}),
|
|
20
65
|
)
|
|
21
66
|
```
|
|
22
67
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
68
|
+
`runtimeFor(context)` returns an `AgentRuntime` already bound to the correct live
|
|
69
|
+
application and principal:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
const runtimeFor = (context: HostContext) =>
|
|
73
|
+
AgentBuilder.bind({
|
|
74
|
+
definition: AssistantAgent,
|
|
75
|
+
host: hostFor(context),
|
|
76
|
+
principal: () => principalFor(context),
|
|
77
|
+
})
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
That distinction is the heart of this adapter:
|
|
81
|
+
|
|
82
|
+
```text
|
|
83
|
+
static
|
|
84
|
+
AssistantAgent
|
|
85
|
+
|
|
|
86
|
+
v
|
|
87
|
+
Agent Native action descriptions
|
|
88
|
+
|
|
89
|
+
per invocation
|
|
90
|
+
verified host caller/context
|
|
91
|
+
|
|
|
92
|
+
v
|
|
93
|
+
resolveRuntime(ctx)
|
|
94
|
+
|
|
|
95
|
+
v
|
|
96
|
+
AgentRuntime
|
|
97
|
+
|
|
|
98
|
+
v
|
|
99
|
+
availability -> authorization -> Message -> update
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The registry describes capabilities. The bound runtime decides whether a
|
|
103
|
+
particular caller may use one **right now**.
|
|
104
|
+
|
|
105
|
+
## What a capability becomes
|
|
106
|
+
|
|
107
|
+
One exposed capability becomes one Agent Native action keyed by capability
|
|
108
|
+
name:
|
|
109
|
+
|
|
110
|
+
| `foldkit-agent` | Agent Native |
|
|
111
|
+
| --- | --- |
|
|
112
|
+
| capability name | action name |
|
|
113
|
+
| description | action description |
|
|
114
|
+
| encoded input Schema | action parameter schema |
|
|
115
|
+
| `AgentRuntime` dispatch | `run` |
|
|
116
|
+
| completion contract | returned success/failure outcome |
|
|
117
|
+
|
|
118
|
+
Each generated entry declares `http: POST`, `requiresAuth: true`, and
|
|
119
|
+
`readOnly: false`. A capability can dispatch a Message, so advertising it as
|
|
120
|
+
read-only could let a planning surface execute real application behavior under
|
|
121
|
+
the wrong assumption.
|
|
28
122
|
|
|
29
|
-
Nothing is written to disk.
|
|
30
|
-
|
|
123
|
+
Nothing is written to disk. The adapter returns the action record Agent Native
|
|
124
|
+
expects; the host decides how that registry is loaded and deployed.
|
|
31
125
|
|
|
32
|
-
|
|
33
|
-
which Model a caller means depends on who is calling. The Runtime it returns must
|
|
34
|
-
already be bound for that caller: when a contract declares `authorize`,
|
|
35
|
-
`Agent.bind` requires a `principal` provider, so the identity mapping stays with
|
|
36
|
-
the application rather than being guessed from `userEmail`.
|
|
126
|
+
## Runtime and identity
|
|
37
127
|
|
|
38
|
-
|
|
128
|
+
`resolveRuntime` runs **per invocation**, not once when actions are registered.
|
|
129
|
+
That is necessary because the action description is static while the Model and
|
|
130
|
+
principal are caller-specific.
|
|
39
131
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
132
|
+
When a contract declares `authorize`, the runtime must be bound with a principal
|
|
133
|
+
provider of the matching type. This adapter intentionally does not infer
|
|
134
|
+
application identity from arbitrary Agent Native context fields such as an email
|
|
135
|
+
address. Mapping an authenticated host caller to your application principal
|
|
136
|
+
belongs to the host/application boundary.
|
|
44
137
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
138
|
+
Availability is dynamic too. A capability can remain present in the static Agent
|
|
139
|
+
Native registry while being unavailable in the current Model; the bound runtime
|
|
140
|
+
refuses it at call time.
|
|
48
141
|
|
|
49
142
|
## What `run` returns
|
|
50
143
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
`{ ok: false, message }`; Agent Native records the call as completed and
|
|
54
|
-
serializes that object as the tool output. A surface that decides success from
|
|
55
|
-
the action's status alone therefore reads a refusal as a success -- read `ok`
|
|
56
|
-
instead. Only a host defect is caught, and it is flattened to a generic message
|
|
57
|
-
so application internals never reach the caller.
|
|
144
|
+
Application refusals are returned as application output, not thrown as adapter
|
|
145
|
+
crashes:
|
|
58
146
|
|
|
59
|
-
|
|
147
|
+
```ts
|
|
148
|
+
{ ok: false, message: '…' }
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
That includes unavailable, unauthorized, cancelled, invalid-input, and failed
|
|
152
|
+
completion outcomes.
|
|
153
|
+
|
|
154
|
+
A successful dispatch/completion returns `ok: true`. Agent Native may consider
|
|
155
|
+
the framework-level action invocation itself complete, so consumers should read
|
|
156
|
+
the returned `ok` value rather than assuming framework completion means the
|
|
157
|
+
application accepted or completed the operation.
|
|
158
|
+
|
|
159
|
+
Only host/adapter defects are flattened to a generic failure message. Internal
|
|
160
|
+
application errors are not exposed to the caller.
|
|
161
|
+
|
|
162
|
+
## Why generate actions instead of writing them twice?
|
|
163
|
+
|
|
164
|
+
The dependency direction stays one-way:
|
|
165
|
+
|
|
166
|
+
```text
|
|
167
|
+
Foldkit Message + update
|
|
168
|
+
|
|
|
169
|
+
foldkit-agent capability
|
|
170
|
+
|
|
|
171
|
+
Agent Native action
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Availability, authorization, input validation, and completion remain in the
|
|
175
|
+
contract/runtime. The generated action adds no authority and no second
|
|
176
|
+
implementation of the transition.
|
|
177
|
+
|
|
178
|
+
If the contract changes, the generated registry changes with it instead of
|
|
179
|
+
leaving a hand-written action beside the application that can drift.
|
|
180
|
+
|
|
181
|
+
An application-local Agent Native action can still override an inherited/package
|
|
182
|
+
action according to Agent Native's own registry rules.
|
|
183
|
+
|
|
184
|
+
## Schema bridge
|
|
60
185
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
to decode once, including transforming schemas such as `NumberFromString`.
|
|
186
|
+
This section is implementation/compatibility detail; it is not required to use
|
|
187
|
+
the adapter.
|
|
64
188
|
|
|
65
|
-
The
|
|
189
|
+
The adapter exposes the capability's **encoded** input Schema as a Standard
|
|
190
|
+
Schema validator and advertises the corresponding JSON Schema to Agent Native.
|
|
191
|
+
That preserves the same boundary `foldkit-agent` uses for transforming schemas
|
|
192
|
+
such as `NumberFromString`: Agent Native validates the encoded input, then the
|
|
193
|
+
bound runtime performs the application's single decode before dispatch.
|
|
66
194
|
|
|
67
|
-
|
|
195
|
+
Agent Native's current schema integration needs validation and JSON Schema
|
|
196
|
+
metadata on the same schema object. With Effect, the two conversion helpers
|
|
197
|
+
provide different halves:
|
|
198
|
+
|
|
199
|
+
| Conversion | `validate` | advertised parameters |
|
|
68
200
|
| --- | --- | --- |
|
|
69
|
-
| `toStandardSchemaV1` | yes |
|
|
201
|
+
| `toStandardSchemaV1` | yes | empty |
|
|
70
202
|
| `toStandardJSONSchemaV1` | no | full |
|
|
71
|
-
|
|
|
72
|
-
| both
|
|
203
|
+
| copied into a fresh object | yes | empty |
|
|
204
|
+
| both called on the same schema object | yes | full |
|
|
205
|
+
|
|
206
|
+
The adapter therefore calls both helpers on the same Effect schema object so its
|
|
207
|
+
identity—and the metadata associated with it—survives.
|
|
208
|
+
|
|
209
|
+
Extra input fields are rejected. Only object input schemas are supported because
|
|
210
|
+
that is the shape Agent Native currently includes in its tool list.
|
|
73
211
|
|
|
74
|
-
|
|
75
|
-
as taking no input. Copying fails because the conversion reads the Effect schema
|
|
76
|
-
itself, so identity has to survive — and both helpers return that same schema,
|
|
77
|
-
sharing one `~standard`, so calling them in turn leaves a single object carrying
|
|
78
|
-
`jsonSchema` and `validate` alike. That is what this package does.
|
|
212
|
+
## Compatibility proof
|
|
79
213
|
|
|
80
|
-
|
|
214
|
+
The adapter is checked against `@agent-native/core@0.177.1` using the real Agent
|
|
215
|
+
Native registry, tool runtime, and schema wrapper rather than stand-ins.
|
|
216
|
+
|
|
217
|
+
Run from the repository root:
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
pnpm exec vitest run packages/agent-native/test/framework.test.ts
|
|
221
|
+
```
|
|
81
222
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
an in-memory PGlite database for the framework's internal metadata lookups.
|
|
223
|
+
No LLM credentials or network server are required; the suite uses an in-memory
|
|
224
|
+
PGlite database for Agent Native's internal metadata lookups.
|
|
85
225
|
|
|
86
|
-
| Framework surface |
|
|
226
|
+
| Framework surface | What the test proves |
|
|
87
227
|
| --- | --- |
|
|
88
|
-
| Package registry | `registerPackageActions` + `autoDiscoverActions` discovers the
|
|
228
|
+
| Package registry | `registerPackageActions` + `autoDiscoverActions` discovers the generated entry; an app-local action file wins a name collision. |
|
|
89
229
|
| Agent tool runtime | `actionsToEngineTools` advertises the encoded schema; `executeAgentToolCall` changes the Foldkit Model for an authorized caller and refuses another caller. |
|
|
90
|
-
| Schema wrapper | `defineAction` derives parameters, preserves transforming input for one decode in Foldkit, and rejects
|
|
230
|
+
| Schema wrapper | `defineAction` derives parameters, preserves transforming input for the one decode in Foldkit, and rejects excess fields. |
|
|
91
231
|
|
|
92
|
-
The
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
because the framework omits other input shapes from its tool list.
|
|
232
|
+
The public adapter types are checked against Agent Native's real `ActionTool`
|
|
233
|
+
type. Agent Native remains a peer/development dependency of this adapter rather
|
|
234
|
+
than a dependency of core `foldkit-agent`.
|
|
96
235
|
|
|
97
|
-
## Limits
|
|
236
|
+
## Limits
|
|
98
237
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
adapters and direct WebMCP adapter.
|
|
238
|
+
This package integrates the Agent Native **action registry and tool runtime**. It
|
|
239
|
+
does not claim to replace every Agent Native subsystem. HTTP deployment, MCP,
|
|
240
|
+
A2A, CLI, UI queries, authentication sessions, and deep links remain concerns of
|
|
241
|
+
the Agent Native host or Foldkit Plus's dedicated adapters.
|
|
104
242
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
to a principal when binding a server-held Runtime. Page-local state still belongs
|
|
108
|
-
to WebMCP; no browser RPC bridge is introduced.
|
|
243
|
+
Page-local browser state still belongs to WebMCP; this package does not add a
|
|
244
|
+
browser RPC bridge.
|
|
109
245
|
|
|
110
|
-
The
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
downstream registry behavior.
|
|
246
|
+
The Agent Native registry keeps the first registration of a name and skips names
|
|
247
|
+
inherited from `Object.prototype`, including `__proto__`. Avoid those names and
|
|
248
|
+
restart the host after changing a registered contract. The record produced here
|
|
249
|
+
preserves such keys, but cannot change downstream registry behavior.
|
|
115
250
|
|
|
116
|
-
|
|
251
|
+
Full HTTP/MCP/A2A deployment tests are outside this package's test suite. This
|
|
252
|
+
is the bounded integration originally tracked in
|
|
117
253
|
[issue #22](https://github.com/doeixd/foldkit-plus/issues/22), not a claim that
|
|
118
|
-
every Agent Native subsystem is independently reusable.
|
|
119
|
-
|
|
254
|
+
every Agent Native subsystem is independently reusable.
|
|
255
|
+
|
|
256
|
+
## Choosing an adapter
|
|
257
|
+
|
|
258
|
+
All four adapters serve the same `AssistantAgent` contract. Multiple adapters
|
|
259
|
+
mean multiple protocol interpretations of one definition, not multiple
|
|
260
|
+
capability declarations.
|
|
261
|
+
|
|
262
|
+
| Where the agent runs | Adapter |
|
|
263
|
+
| --- | --- |
|
|
264
|
+
| In the page, beside the user | [`foldkit-agent-webmcp`](../agent-webmcp) |
|
|
265
|
+
| An external MCP client, over stdio or HTTP | [`foldkit-agent-mcp`](../agent-mcp) |
|
|
266
|
+
| Another agent, over A2A | [`foldkit-agent-a2a`](../agent-a2a) |
|
|
267
|
+
| An Agent Native host | `foldkit-agent-native` |
|
|
268
|
+
|
|
269
|
+
## See also
|
|
270
|
+
|
|
271
|
+
- [Agents guide](../../docs/agents.md) — builder → contract → runtime and the authority model.
|
|
272
|
+
- [`foldkit-agent`](../agent) — the protocol-neutral contract and runtime.
|
|
273
|
+
- [`examples/todo`](../../examples/todo) — a focused contract served through adapters.
|
package/dist/index.d.mts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { Agent } from "foldkit-agent";
|
|
2
2
|
import { ActionTool } from "@agent-native/core/server";
|
|
3
|
-
import { StandardSchemaV1 } from "effect/StandardSchema";
|
|
3
|
+
import { StandardJSONSchemaV1, StandardSchemaV1 } from "effect/StandardSchema";
|
|
4
4
|
//#region src/actions.d.ts
|
|
5
5
|
type AgentRuntime = Agent.AgentRuntime<any, any, any, any, any>;
|
|
6
6
|
/**
|
|
@@ -31,7 +31,8 @@ interface ActionEntry {
|
|
|
31
31
|
readonly parameters: NonNullable<ActionTool['parameters']>;
|
|
32
32
|
};
|
|
33
33
|
readonly run: (args: unknown, context?: ActionRunContext) => Promise<ActionResult>;
|
|
34
|
-
|
|
34
|
+
/** Validates input and carries the JSON Schema its parameters are advertised from. */
|
|
35
|
+
readonly schema: StandardSchemaV1<unknown, unknown> & StandardJSONSchemaV1<unknown, unknown>;
|
|
35
36
|
readonly http: {
|
|
36
37
|
readonly method: 'POST';
|
|
37
38
|
};
|
|
@@ -47,8 +48,8 @@ interface ActionEntry {
|
|
|
47
48
|
*/
|
|
48
49
|
readonly readOnly: false;
|
|
49
50
|
}
|
|
50
|
-
interface ActionsOptions {
|
|
51
|
-
readonly definition: Agent.Definition<any, any, any,
|
|
51
|
+
interface ActionsOptions<ByName = Record<string, unknown>> {
|
|
52
|
+
readonly definition: Agent.Definition<any, any, any, ByName, any>;
|
|
52
53
|
/**
|
|
53
54
|
* Resolves the Runtime for one request.
|
|
54
55
|
*
|
|
@@ -83,10 +84,15 @@ interface ActionsOptions {
|
|
|
83
84
|
* )
|
|
84
85
|
* ```
|
|
85
86
|
*/
|
|
86
|
-
|
|
87
|
+
/**
|
|
88
|
+
* The registry, keyed by the contract's capability names when they are known,
|
|
89
|
+
* so a registered name needs no lookup check and a mistyped one does not compile.
|
|
90
|
+
*/
|
|
91
|
+
type ActionRegistry<ByName = Record<string, unknown>> = string extends keyof ByName ? Record<string, ActionEntry> : { readonly [Name in keyof ByName]: ActionEntry; };
|
|
92
|
+
declare const actions: <ByName = Record<string, unknown>>(options: ActionsOptions<ByName>) => ActionRegistry<ByName>;
|
|
87
93
|
declare namespace agentNative_d_exports {
|
|
88
|
-
export { ActionEntry, ActionResult, ActionRunContext, ActionsOptions, actions };
|
|
94
|
+
export { ActionEntry, ActionRegistry, ActionResult, ActionRunContext, ActionsOptions, actions };
|
|
89
95
|
}
|
|
90
96
|
//#endregion
|
|
91
|
-
export { type ActionEntry, type ActionResult, type ActionRunContext, type ActionsOptions, agentNative_d_exports as AgentNative };
|
|
97
|
+
export { type ActionEntry, type ActionRegistry, type ActionResult, type ActionRunContext, type ActionsOptions, agentNative_d_exports as AgentNative };
|
|
92
98
|
//# sourceMappingURL=index.d.mts.map
|
package/dist/index.d.mts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/actions.ts","../src/agentNative.ts"],"mappings":";;;;KAKK,eAAe,MAAM;;;;;;;;;UAUT;WACN;WACA;;;UAIM;WACN;;WAEA;;WAEA;WACA;;;UAIM;WACN;aACE;aACA,YAAY,YAAY;;WAE1B,MAAM,eAAe,UAAU,qBAAqB,QAAQ
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/actions.ts","../src/agentNative.ts"],"mappings":";;;;KAKK,eAAe,MAAM;;;;;;;;;UAUT;WACN;WACA;;;UAIM;WACN;;WAEA;;WAEA;WACA;;;UAIM;WACN;aACE;aACA,YAAY,YAAY;;WAE1B,MAAM,eAAe,UAAU,qBAAqB,QAAQ;;WAE5D,QAAQ,qCAAqC;WAC7C;aAAiB;;;WAEjB;;;;;;;;;WASA;;UAwBM,eAAe,SAAS;WAC9B,YAAY,MAAM,0BAA0B;;;;;;;;;;WAW5C,iBAAiB,SAAS,qBAAqB,eAAe,QAAQ;;WAGtE;;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BC,eAAe,SAAS,gDAAgD,SAChF,eAAe,2BACH,cAAc,SAAS;cAE1B,UAAW,SAAS,yBAC/B,SAAS,eAAe,YACvB,eAAe"}
|
package/dist/index.mjs
CHANGED
|
@@ -15,32 +15,7 @@ import { Effect, Schema } from "effect";
|
|
|
15
15
|
* turn leaves a single object carrying both. Copying them into a new object
|
|
16
16
|
* would not work: the conversion reads the Effect schema, so identity matters.
|
|
17
17
|
*/
|
|
18
|
-
const describedSchema = (schema) => {
|
|
19
|
-
const described = Schema.toStandardJSONSchemaV1(schema);
|
|
20
|
-
Schema.toStandardSchemaV1(schema, { parseOptions: { onExcessProperty: "error" } });
|
|
21
|
-
return described;
|
|
22
|
-
};
|
|
23
|
-
/**
|
|
24
|
-
* Compiles the exposed capabilities into a package action registry.
|
|
25
|
-
*
|
|
26
|
-
* Hand the result to `registerPackageActions` from `@agent-native/core/server`,
|
|
27
|
-
* which merges it into the registry every surface reads. Nothing is written to
|
|
28
|
-
* disk, so no generated action can outlive the capability it came from.
|
|
29
|
-
*
|
|
30
|
-
* `run` only dispatches. Application behaviour stays in `update`, and the action
|
|
31
|
-
* adds no authority of its own: availability, authorization and input
|
|
32
|
-
* validation all still happen in the contract.
|
|
33
|
-
*
|
|
34
|
-
* @example
|
|
35
|
-
* ```ts
|
|
36
|
-
* registerPackageActions(
|
|
37
|
-
* AgentNative.actions({
|
|
38
|
-
* definition: AppAgent,
|
|
39
|
-
* resolveRuntime: ctx => runtimeFor(ctx),
|
|
40
|
-
* }),
|
|
41
|
-
* )
|
|
42
|
-
* ```
|
|
43
|
-
*/
|
|
18
|
+
const describedSchema = (schema) => Schema.toStandardSchemaV1(Schema.toStandardJSONSchemaV1(schema), { parseOptions: { onExcessProperty: "error" } });
|
|
44
19
|
const actions = (options) => {
|
|
45
20
|
const transport = options.transport ?? "agent-native";
|
|
46
21
|
const entries = Object.create(null);
|
package/dist/index.mjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.mjs","names":[],"sources":["../src/actions.ts","../src/agentNative.ts"],"sourcesContent":["import { Agent } from 'foldkit-agent'\nimport type { ActionTool } from '@agent-native/core/server'\nimport { Effect, Schema } from 'effect'\nimport type { StandardSchemaV1 } from 'effect/StandardSchema'\n\ntype AgentRuntime = Agent.AgentRuntime<any, any, any, any, any>\n\n/**\n * The request context Agent Native hands an action.\n *\n * Deliberately narrower than the framework's own `ActionRunContext`: the\n * adapter promises only the identity a principal mapper needs, so its public\n * surface does not grow with the framework's context. The framework still\n * passes its full context through at runtime.\n */\nexport interface ActionRunContext {\n readonly userEmail?: string | undefined\n readonly orgId?: string | null | undefined\n}\n\n/** What an action reports back. `run` never decides anything itself. */\nexport interface ActionResult {\n readonly ok: boolean\n /** The Message tag that was dispatched, when one was. */\n readonly tag?: string | undefined\n /** How the operation finished, when the capability declares completion. */\n readonly completion?: 'completed' | 'failed' | undefined\n readonly message: string\n}\n\n/** One entry of the record `registerPackageActions` takes. */\nexport interface ActionEntry {\n readonly tool: {\n readonly description: string\n readonly parameters: NonNullable<ActionTool['parameters']>\n }\n readonly run: (args: unknown, context?: ActionRunContext) => Promise<ActionResult>\n readonly schema: StandardSchemaV1<unknown, unknown>\n readonly http: { readonly method: 'POST' }\n /** Defaults to true in the framework; stated so it is not left to a default. */\n readonly requiresAuth: boolean\n /**\n * Always false. A capability dispatches a Message into `update`, so it is a\n * write however little it changes.\n *\n * This feeds plan-mode classification, where the dangerous direction is\n * claiming read-only: plan mode would then run it for real. A resource read\n * would be the read-only case, and resources are not exposed as actions yet.\n */\n readonly readOnly: false\n}\n\n/**\n * A Standard Schema that both validates and advertises its shape.\n *\n * Neither Effect helper does both alone, and the difference is silent:\n * `toStandardSchemaV1` carries `validate` but no `jsonSchema`, and\n * `defineAction` accepts it while advertising a tool that takes **no input**;\n * `toStandardJSONSchemaV1` carries the `jsonSchema` those parameters come from\n * but no `validate`.\n *\n * Both return the schema itself and share one `~standard`, so calling them in\n * turn leaves a single object carrying both. Copying them into a new object\n * would not work: the conversion reads the Effect schema, so identity matters.\n */\nconst describedSchema = (\n schema:
|
|
1
|
+
{"version":3,"file":"index.mjs","names":[],"sources":["../src/actions.ts","../src/agentNative.ts"],"sourcesContent":["import { Agent } from 'foldkit-agent'\nimport type { ActionTool } from '@agent-native/core/server'\nimport { Effect, Schema } from 'effect'\nimport type { StandardJSONSchemaV1, StandardSchemaV1 } from 'effect/StandardSchema'\n\ntype AgentRuntime = Agent.AgentRuntime<any, any, any, any, any>\n\n/**\n * The request context Agent Native hands an action.\n *\n * Deliberately narrower than the framework's own `ActionRunContext`: the\n * adapter promises only the identity a principal mapper needs, so its public\n * surface does not grow with the framework's context. The framework still\n * passes its full context through at runtime.\n */\nexport interface ActionRunContext {\n readonly userEmail?: string | undefined\n readonly orgId?: string | null | undefined\n}\n\n/** What an action reports back. `run` never decides anything itself. */\nexport interface ActionResult {\n readonly ok: boolean\n /** The Message tag that was dispatched, when one was. */\n readonly tag?: string | undefined\n /** How the operation finished, when the capability declares completion. */\n readonly completion?: 'completed' | 'failed' | undefined\n readonly message: string\n}\n\n/** One entry of the record `registerPackageActions` takes. */\nexport interface ActionEntry {\n readonly tool: {\n readonly description: string\n readonly parameters: NonNullable<ActionTool['parameters']>\n }\n readonly run: (args: unknown, context?: ActionRunContext) => Promise<ActionResult>\n /** Validates input and carries the JSON Schema its parameters are advertised from. */\n readonly schema: StandardSchemaV1<unknown, unknown> & StandardJSONSchemaV1<unknown, unknown>\n readonly http: { readonly method: 'POST' }\n /** Defaults to true in the framework; stated so it is not left to a default. */\n readonly requiresAuth: boolean\n /**\n * Always false. A capability dispatches a Message into `update`, so it is a\n * write however little it changes.\n *\n * This feeds plan-mode classification, where the dangerous direction is\n * claiming read-only: plan mode would then run it for real. A resource read\n * would be the read-only case, and resources are not exposed as actions yet.\n */\n readonly readOnly: false\n}\n\n/**\n * A Standard Schema that both validates and advertises its shape.\n *\n * Neither Effect helper does both alone, and the difference is silent:\n * `toStandardSchemaV1` carries `validate` but no `jsonSchema`, and\n * `defineAction` accepts it while advertising a tool that takes **no input**;\n * `toStandardJSONSchemaV1` carries the `jsonSchema` those parameters come from\n * but no `validate`.\n *\n * Both return the schema itself and share one `~standard`, so calling them in\n * turn leaves a single object carrying both. Copying them into a new object\n * would not work: the conversion reads the Effect schema, so identity matters.\n */\nconst describedSchema = (\n schema: Schema.Codec<unknown, unknown>,\n): StandardSchemaV1<unknown, unknown> & StandardJSONSchemaV1<unknown, unknown> =>\n // Stripping fields here would hide invalid input from dispatch's strict decoder.\n Schema.toStandardSchemaV1(Schema.toStandardJSONSchemaV1(schema), {\n parseOptions: { onExcessProperty: 'error' },\n })\n\nexport interface ActionsOptions<ByName = Record<string, unknown>> {\n readonly definition: Agent.Definition<any, any, any, ByName, any>\n\n /**\n * Resolves the Runtime for one request.\n *\n * Called per invocation, because which Model a caller means depends on who is\n * calling. The Runtime it returns must already be bound for that caller: when\n * a contract declares `authorize`, `Agent.bind` requires a `principal`\n * provider, so the identity mapping stays with the application instead of\n * being guessed here from `userEmail`.\n */\n readonly resolveRuntime: (context: ActionRunContext) => AgentRuntime | Promise<AgentRuntime>\n\n /** Recorded on the invocation, so an audit log can tell these apart. */\n readonly transport?: string | undefined\n}\n\n/**\n * Compiles the exposed capabilities into a package action registry.\n *\n * Hand the result to `registerPackageActions` from `@agent-native/core/server`,\n * which merges it into the registry every surface reads. Nothing is written to\n * disk, so no generated action can outlive the capability it came from.\n *\n * `run` only dispatches. Application behaviour stays in `update`, and the action\n * adds no authority of its own: availability, authorization and input\n * validation all still happen in the contract.\n *\n * @example\n * ```ts\n * registerPackageActions(\n * AgentNative.actions({\n * definition: AppAgent,\n * resolveRuntime: ctx => runtimeFor(ctx),\n * }),\n * )\n * ```\n */\n/**\n * The registry, keyed by the contract's capability names when they are known,\n * so a registered name needs no lookup check and a mistyped one does not compile.\n */\nexport type ActionRegistry<ByName = Record<string, unknown>> = string extends keyof ByName\n ? Record<string, ActionEntry>\n : { readonly [Name in keyof ByName]: ActionEntry }\n\nexport const actions = <ByName = Record<string, unknown>>(\n options: ActionsOptions<ByName>,\n): ActionRegistry<ByName> => {\n const transport = options.transport ?? 'agent-native'\n const entries: Record<string, ActionEntry> = Object.create(null)\n\n for (const variant of options.definition.messages.variants) {\n if (variant.inputJsonSchema.type !== 'object') {\n throw new Error(`Agent Native capability \"${variant.name}\" requires an object input schema`)\n }\n entries[variant.name] = {\n tool: {\n description: variant.description,\n parameters: {\n properties: {},\n ...variant.inputJsonSchema,\n } as NonNullable<ActionTool['parameters']>,\n },\n // Validated on the *encoded* side. The framework hands `run` whatever\n // this schema parsed, and `run` hands that to `dispatchUnknown`, which\n // decodes. A decoding schema here would decode a transforming input\n // twice, so the contract would then reject its own validated value.\n schema: describedSchema(Schema.toEncoded(variant.inputSchema)),\n http: { method: 'POST' },\n requiresAuth: true,\n readOnly: false,\n\n run: async (args: unknown, context?: ActionRunContext): Promise<ActionResult> => {\n // Resolution is the application's code, and its throw is deliberate --\n // a principal mapper refusing an unauthenticated caller, say. Let it\n // through rather than reporting it as this capability failing.\n const agent = await options.resolveRuntime(context ?? {})\n\n let outcome\n try {\n outcome = await Effect.runPromise(\n Effect.result(agent.messages.dispatchUnknown(variant.name, args, { transport })),\n )\n } catch {\n // `Effect.result` captures expected failures but not defects, and a\n // defect's text may carry application internals.\n return { ok: false, message: `Capability \"${variant.name}\" failed unexpectedly` }\n }\n\n if (outcome._tag === 'Failure') {\n return { ok: false, message: outcome.failure.message }\n }\n\n const result = outcome.success\n const summary = Agent.summarize(result)\n return {\n ok: summary.ok,\n tag: result.tag,\n ...(result.completion === undefined ? {} : { completion: result.completion.status }),\n message: summary.text,\n }\n },\n }\n }\n\n // Keyed by exactly the exposed names, which is what ByName records.\n return entries as ActionRegistry<ByName>\n}\n","export {\n actions,\n type ActionEntry,\n type ActionRegistry,\n type ActionResult,\n type ActionRunContext,\n type ActionsOptions,\n} from './actions.js'\n"],"mappings":";;;;;;;;;;;;;;;;;AAkEA,MAAM,mBACJ,WAGA,OAAO,mBAAmB,OAAO,uBAAuB,MAAM,GAAG,EAC/D,cAAc,EAAE,kBAAkB,QAAQ,EAC5C,CAAC;AAiDH,MAAa,WACX,YAC2B;CAC3B,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,UAAuC,OAAO,OAAO,IAAI;CAE/D,KAAK,MAAM,WAAW,QAAQ,WAAW,SAAS,UAAU;EAC1D,IAAI,QAAQ,gBAAgB,SAAS,UACnC,MAAM,IAAI,MAAM,4BAA4B,QAAQ,KAAK,kCAAkC;EAE7F,QAAQ,QAAQ,QAAQ;GACtB,MAAM;IACJ,aAAa,QAAQ;IACrB,YAAY;KACV,YAAY,CAAC;KACb,GAAG,QAAQ;IACb;GACF;GAKA,QAAQ,gBAAgB,OAAO,UAAU,QAAQ,WAAW,CAAC;GAC7D,MAAM,EAAE,QAAQ,OAAO;GACvB,cAAc;GACd,UAAU;GAEV,KAAK,OAAO,MAAe,YAAsD;IAI/E,MAAM,QAAQ,MAAM,QAAQ,eAAe,WAAW,CAAC,CAAC;IAExD,IAAI;IACJ,IAAI;KACF,UAAU,MAAM,OAAO,WACrB,OAAO,OAAO,MAAM,SAAS,gBAAgB,QAAQ,MAAM,MAAM,EAAE,UAAU,CAAC,CAAC,CACjF;IACF,QAAQ;KAGN,OAAO;MAAE,IAAI;MAAO,SAAS,eAAe,QAAQ,KAAK;KAAuB;IAClF;IAEA,IAAI,QAAQ,SAAS,WACnB,OAAO;KAAE,IAAI;KAAO,SAAS,QAAQ,QAAQ;IAAQ;IAGvD,MAAM,SAAS,QAAQ;IACvB,MAAM,UAAU,MAAM,UAAU,MAAM;IACtC,OAAO;KACL,IAAI,QAAQ;KACZ,KAAK,OAAO;KACZ,GAAI,OAAO,eAAe,KAAA,IAAY,CAAC,IAAI,EAAE,YAAY,OAAO,WAAW,OAAO;KAClF,SAAS,QAAQ;IACnB;GACF;EACF;CACF;CAGA,OAAO;AACT"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldkit-agent-native",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Agent Native adapter for foldkit-agent. Compiles an exposed Foldkit contract into Agent Native actions.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"foldkit",
|
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
"@agent-native/core": "0.177.1",
|
|
41
41
|
"effect": "^4.0.0-rc.112",
|
|
42
42
|
"foldkit": "^0.158.2",
|
|
43
|
-
"foldkit-agent": "^0.
|
|
43
|
+
"foldkit-agent": "^0.3.0"
|
|
44
44
|
},
|
|
45
45
|
"devDependencies": {
|
|
46
46
|
"@agent-native/core": "0.177.1",
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
"foldkit": "0.158.2",
|
|
49
49
|
"tsdown": "^0.23.0",
|
|
50
50
|
"typescript": "^5.7.2",
|
|
51
|
-
"foldkit-agent": "0.
|
|
51
|
+
"foldkit-agent": "0.3.0"
|
|
52
52
|
},
|
|
53
53
|
"scripts": {
|
|
54
54
|
"build": "tsdown",
|