@open-artifact/protocol 0.0.0-stage → 0.2.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/LICENSE +202 -0
- package/NOTICE +5 -0
- package/README.md +5 -2
- package/package.json +33 -4
- package/src/errors.d.ts +36 -0
- package/src/errors.js +46 -0
- package/src/harness.d.ts +293 -0
- package/src/harness.js +38 -0
- package/src/index.d.ts +28 -0
- package/src/index.js +28 -0
- package/src/library.d.ts +239 -0
- package/src/library.js +30 -0
- package/src/manifest.d.ts +153 -0
- package/src/manifest.js +16 -0
- package/src/prompt.d.ts +40 -0
- package/src/prompt.js +139 -0
- package/src/refs.d.ts +51 -0
- package/src/refs.js +58 -0
- package/src/settings.d.ts +53 -0
- package/src/settings.js +21 -0
- package/src/shell.d.ts +359 -0
- package/src/shell.js +60 -0
- package/src/tools.d.ts +207 -0
- package/src/tools.js +163 -0
- package/src/type-server.d.ts +251 -0
- package/src/type-server.js +60 -0
- package/src/wake.d.ts +149 -0
- package/src/wake.js +135 -0
package/src/tools.d.ts
ADDED
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The agent's tools: `Artifact`, `ArtifactData` and `ArtifactComments`.
|
|
3
|
+
*
|
|
4
|
+
* The daemon implements them once; MCP (`POST /mcp`), the Harness API's
|
|
5
|
+
* `tools.call`, the HTTP polling API and the `open-artifact` command line all land
|
|
6
|
+
* there. Adapters that register the tools in their harness themselves use
|
|
7
|
+
* {@link TOOL_SCHEMAS} and {@link TOOL_DESCRIPTIONS}.
|
|
8
|
+
*/
|
|
9
|
+
/** A JSON Schema property, the subset the tool schemas use. */
|
|
10
|
+
export interface JsonSchemaProperty {
|
|
11
|
+
type?: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
|
|
12
|
+
description?: string;
|
|
13
|
+
enum?: readonly string[];
|
|
14
|
+
properties?: Record<string, JsonSchemaProperty>;
|
|
15
|
+
items?: JsonSchemaProperty;
|
|
16
|
+
additionalProperties?: boolean;
|
|
17
|
+
}
|
|
18
|
+
/** A tool's input schema. */
|
|
19
|
+
export interface ToolInputSchema {
|
|
20
|
+
type: 'object';
|
|
21
|
+
properties: Record<string, JsonSchemaProperty>;
|
|
22
|
+
required?: readonly string[];
|
|
23
|
+
}
|
|
24
|
+
/** Tool names. */
|
|
25
|
+
export type ToolName = 'Artifact' | 'ArtifactData' | 'ArtifactComments';
|
|
26
|
+
/** A tool as MCP `tools/list` and `tools.list` describe it. */
|
|
27
|
+
export interface ToolDefinition {
|
|
28
|
+
name: ToolName;
|
|
29
|
+
description: string;
|
|
30
|
+
inputSchema: ToolInputSchema;
|
|
31
|
+
/** MCP tool annotations: hints an app's approval check reads. */
|
|
32
|
+
annotations?: ToolAnnotations;
|
|
33
|
+
}
|
|
34
|
+
/** MCP tool annotations (hints, not guarantees). */
|
|
35
|
+
export interface ToolAnnotations {
|
|
36
|
+
title?: string;
|
|
37
|
+
readOnlyHint?: boolean;
|
|
38
|
+
destructiveHint?: boolean;
|
|
39
|
+
idempotentHint?: boolean;
|
|
40
|
+
/** false: the tool works only on this computer's artifacts, not with an outside service. */
|
|
41
|
+
openWorldHint?: boolean;
|
|
42
|
+
}
|
|
43
|
+
/** `Artifact` actions. */
|
|
44
|
+
export declare const ARTIFACT_ACTIONS: readonly ["quickstart", "list", "publish", "read", "open", "call", "adopt", "delete", "share"];
|
|
45
|
+
/** `ArtifactData` actions. */
|
|
46
|
+
export declare const DATA_ACTIONS: readonly ["get", "list", "query", "set", "update", "delete", "str_replace", "batch"];
|
|
47
|
+
/** `ArtifactComments` actions. */
|
|
48
|
+
export declare const COMMENTS_ACTIONS: readonly ["read", "reply", "resolve", "reopen", "wait"];
|
|
49
|
+
export type ArtifactAction = (typeof ARTIFACT_ACTIONS)[number];
|
|
50
|
+
export type DataAction = (typeof DATA_ACTIONS)[number];
|
|
51
|
+
export type CommentsAction = (typeof COMMENTS_ACTIONS)[number];
|
|
52
|
+
/** A file to write with `publish`: text, or base64 bytes; `null` deletes. */
|
|
53
|
+
export type PublishFile = string | {
|
|
54
|
+
content: string;
|
|
55
|
+
encoding?: 'utf8' | 'base64';
|
|
56
|
+
} | null;
|
|
57
|
+
/** `Artifact` arguments. */
|
|
58
|
+
export interface ArtifactArgs {
|
|
59
|
+
action?: ArtifactAction;
|
|
60
|
+
intent?: string;
|
|
61
|
+
scope?: 'types' | 'mine' | 'all';
|
|
62
|
+
type_url?: string;
|
|
63
|
+
title?: string;
|
|
64
|
+
folder?: string;
|
|
65
|
+
url?: string;
|
|
66
|
+
files?: Record<string, PublishFile>;
|
|
67
|
+
path?: string;
|
|
68
|
+
/** read: several files at once. */
|
|
69
|
+
paths?: string[];
|
|
70
|
+
/** list: only artifacts of this type (id or type_url). */
|
|
71
|
+
type?: string;
|
|
72
|
+
/** list: only artifacts whose title contains it. quickstart: same as intent. */
|
|
73
|
+
query?: string;
|
|
74
|
+
/** list: page size (default 50, at most 200). */
|
|
75
|
+
limit?: number;
|
|
76
|
+
/** list: `next_cursor` of the previous page. */
|
|
77
|
+
cursor?: string;
|
|
78
|
+
/** publish with url: per file, the sha256 it must still have, `null` (must not exist) or `"*"` (any). */
|
|
79
|
+
if_match?: Record<string, string | null>;
|
|
80
|
+
/** publish with url: run the type's `check` action after writing. */
|
|
81
|
+
check?: boolean;
|
|
82
|
+
/** publish without url: open the page after the first write (`after_first_write`) or right away (`now`). */
|
|
83
|
+
open?: 'after_first_write' | 'now';
|
|
84
|
+
/** quickstart: list existing artifacts the recommended type can use (default true). */
|
|
85
|
+
related?: boolean;
|
|
86
|
+
name?: string;
|
|
87
|
+
args?: Record<string, unknown>;
|
|
88
|
+
/** open: the Shell panel to show the person, `share` (its Share panel) or `export` (its Export tab). */
|
|
89
|
+
panel?: ArtifactPanel;
|
|
90
|
+
/**
|
|
91
|
+
* Refused: only the person changes sharing, in the Shell's Share panel.
|
|
92
|
+
* Kept here so an agent that still sends them gets an answer that says so.
|
|
93
|
+
*/
|
|
94
|
+
lan?: boolean;
|
|
95
|
+
links?: {
|
|
96
|
+
editor?: boolean;
|
|
97
|
+
commenter?: boolean;
|
|
98
|
+
viewer?: boolean;
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
/** The Shell panels `open` can show: the Share panel, or its Export tab. */
|
|
102
|
+
export declare const ARTIFACT_PANELS: readonly ["share", "export"];
|
|
103
|
+
export type ArtifactPanel = (typeof ARTIFACT_PANELS)[number];
|
|
104
|
+
/** One write of an `ArtifactData` batch. */
|
|
105
|
+
export interface DataWrite {
|
|
106
|
+
op: 'set' | 'update' | 'delete' | 'str_replace';
|
|
107
|
+
path?: string;
|
|
108
|
+
collection?: string;
|
|
109
|
+
doc_id?: string;
|
|
110
|
+
data?: Record<string, unknown>;
|
|
111
|
+
file_path?: string;
|
|
112
|
+
/** The sha256 read returned: write only while the document still has it. `null`: only while it does not exist. `"*"`: whatever it is. */
|
|
113
|
+
if_match?: string | null;
|
|
114
|
+
/** str_replace: the text field, as a dot path. */
|
|
115
|
+
field?: string;
|
|
116
|
+
/** str_replace: the passage to replace; it must occur once. */
|
|
117
|
+
old?: string;
|
|
118
|
+
/** str_replace: what replaces it. */
|
|
119
|
+
new?: string;
|
|
120
|
+
}
|
|
121
|
+
/** A `query` condition, as pages give it. */
|
|
122
|
+
export interface DataWhere {
|
|
123
|
+
field: string;
|
|
124
|
+
op: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in' | 'array-contains';
|
|
125
|
+
value: unknown;
|
|
126
|
+
}
|
|
127
|
+
/** `ArtifactData` arguments. */
|
|
128
|
+
export interface ArtifactDataArgs {
|
|
129
|
+
action: DataAction;
|
|
130
|
+
url: string;
|
|
131
|
+
collection?: string;
|
|
132
|
+
doc_id?: string;
|
|
133
|
+
path?: string;
|
|
134
|
+
data?: Record<string, unknown>;
|
|
135
|
+
file_path?: string;
|
|
136
|
+
writes?: DataWrite[];
|
|
137
|
+
/** query: conditions that all hold. */
|
|
138
|
+
where?: DataWhere[];
|
|
139
|
+
/** query: one sort. */
|
|
140
|
+
order_by?: {
|
|
141
|
+
field: string;
|
|
142
|
+
dir?: 'asc' | 'desc';
|
|
143
|
+
};
|
|
144
|
+
/** list / query: page size (default 100, at most 1000). */
|
|
145
|
+
limit?: number;
|
|
146
|
+
/** list / query: the `next_cursor` of the previous page. */
|
|
147
|
+
cursor?: string;
|
|
148
|
+
/** set / update / delete / str_replace: the sha256 read returned, `null` or `"*"` (see {@link DataWrite.if_match}). */
|
|
149
|
+
if_match?: string | null;
|
|
150
|
+
field?: string;
|
|
151
|
+
old?: string;
|
|
152
|
+
new?: string;
|
|
153
|
+
/** get / list / query: write the result to this JSON file and return only its path and counts. */
|
|
154
|
+
out_file?: string;
|
|
155
|
+
}
|
|
156
|
+
/** `ArtifactComments` arguments. */
|
|
157
|
+
export interface ArtifactCommentsArgs {
|
|
158
|
+
action: CommentsAction;
|
|
159
|
+
url?: string;
|
|
160
|
+
thread_id?: string;
|
|
161
|
+
text?: string;
|
|
162
|
+
resolve?: boolean;
|
|
163
|
+
all?: boolean;
|
|
164
|
+
timeout_ms?: number;
|
|
165
|
+
/** read: only threads with a message at or after this time (ISO 8601 or ms since 1970). */
|
|
166
|
+
since?: string | number;
|
|
167
|
+
/** reply: send the same text as your last reply in the thread again. */
|
|
168
|
+
acknowledge_duplicate?: boolean;
|
|
169
|
+
}
|
|
170
|
+
/** Arguments by tool name. */
|
|
171
|
+
export interface ToolArgs {
|
|
172
|
+
Artifact: ArtifactArgs;
|
|
173
|
+
ArtifactData: ArtifactDataArgs;
|
|
174
|
+
ArtifactComments: ArtifactCommentsArgs;
|
|
175
|
+
}
|
|
176
|
+
/**
|
|
177
|
+
* A tool's result: the action's own fields, or `error`. `messages` carries
|
|
178
|
+
* wake messages that waited for the calling session, as plain text the
|
|
179
|
+
* agent reads after the result.
|
|
180
|
+
*/
|
|
181
|
+
export type ToolCallResult = Record<string, unknown> & {
|
|
182
|
+
error?: {
|
|
183
|
+
code: string;
|
|
184
|
+
message: string;
|
|
185
|
+
fix?: string;
|
|
186
|
+
};
|
|
187
|
+
/** The obvious next call. */
|
|
188
|
+
next?: string;
|
|
189
|
+
/** A fixed remark about this kind of result. */
|
|
190
|
+
note?: string;
|
|
191
|
+
/** Remarks about this call. */
|
|
192
|
+
notes?: string[];
|
|
193
|
+
/** For a conflict: what the conflicting files or documents are now. */
|
|
194
|
+
current?: unknown;
|
|
195
|
+
messages?: string[];
|
|
196
|
+
};
|
|
197
|
+
/** The tools' argument schemas (JSON Schema). */
|
|
198
|
+
export declare const TOOL_SCHEMAS: Record<ToolName, ToolInputSchema>;
|
|
199
|
+
/** The tools' descriptions: what each action does and when to use it. Argument details are in the schemas. */
|
|
200
|
+
export declare const TOOL_DESCRIPTIONS: Record<ToolName, string>;
|
|
201
|
+
/**
|
|
202
|
+
* The tools' MCP annotations. All three work only on this computer's artifact folders, so none is open-world: an
|
|
203
|
+
* app's approval check (Cursor's auto-review) would otherwise take a comment reply for a write to an outside service.
|
|
204
|
+
*/
|
|
205
|
+
export declare const TOOL_ANNOTATIONS: Record<ToolName, ToolAnnotations>;
|
|
206
|
+
/** Tool definitions in MCP shape. */
|
|
207
|
+
export declare const TOOL_DEFINITIONS: ToolDefinition[];
|
package/src/tools.js
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The agent's tools: `Artifact`, `ArtifactData` and `ArtifactComments`.
|
|
3
|
+
*
|
|
4
|
+
* The daemon implements them once; MCP (`POST /mcp`), the Harness API's
|
|
5
|
+
* `tools.call`, the HTTP polling API and the `open-artifact` command line all land
|
|
6
|
+
* there. Adapters that register the tools in their harness themselves use
|
|
7
|
+
* {@link TOOL_SCHEMAS} and {@link TOOL_DESCRIPTIONS}.
|
|
8
|
+
*/
|
|
9
|
+
/** `Artifact` actions. */
|
|
10
|
+
export const ARTIFACT_ACTIONS = ['quickstart', 'list', 'publish', 'read', 'open', 'call', 'adopt', 'delete', 'share'];
|
|
11
|
+
/** `ArtifactData` actions. */
|
|
12
|
+
export const DATA_ACTIONS = ['get', 'list', 'query', 'set', 'update', 'delete', 'str_replace', 'batch'];
|
|
13
|
+
/** `ArtifactComments` actions. */
|
|
14
|
+
export const COMMENTS_ACTIONS = ['read', 'reply', 'resolve', 'reopen', 'wait'];
|
|
15
|
+
/** The Shell panels `open` can show: the Share panel, or its Export tab. */
|
|
16
|
+
export const ARTIFACT_PANELS = ['share', 'export'];
|
|
17
|
+
const ARTIFACT_SCHEMA = {
|
|
18
|
+
type: 'object',
|
|
19
|
+
properties: {
|
|
20
|
+
action: {
|
|
21
|
+
type: 'string',
|
|
22
|
+
enum: ARTIFACT_ACTIONS,
|
|
23
|
+
description: 'What to do. Omitted: publish.',
|
|
24
|
+
},
|
|
25
|
+
intent: {
|
|
26
|
+
type: 'string',
|
|
27
|
+
description: 'quickstart: what is being made (design, slides, whiteboard, document, data, other), or a few words about it.',
|
|
28
|
+
},
|
|
29
|
+
scope: {
|
|
30
|
+
type: 'string',
|
|
31
|
+
enum: ['types', 'mine', 'all'],
|
|
32
|
+
description: "list: the installed types, this session's and this workspace's artifacts (default), or every artifact.",
|
|
33
|
+
},
|
|
34
|
+
type: { type: 'string', description: 'list: only artifacts of this type (an id, or open-artifact://type/<id>).' },
|
|
35
|
+
query: { type: 'string', description: 'list: only artifacts whose title contains this text.' },
|
|
36
|
+
limit: { type: 'integer', description: 'list: how many to return (default 50, at most 200).' },
|
|
37
|
+
cursor: { type: 'string', description: 'list: the next_cursor of the previous page.' },
|
|
38
|
+
type_url: {
|
|
39
|
+
type: 'string',
|
|
40
|
+
description: 'publish without url: the type to create from (open-artifact://type/<id>, from quickstart). read without url: the type to describe.',
|
|
41
|
+
},
|
|
42
|
+
title: { type: 'string', description: "publish without url: the new artifact's name." },
|
|
43
|
+
folder: {
|
|
44
|
+
type: 'string',
|
|
45
|
+
description: "publish without url, or adopt: where the artifact's folder goes (absolute, or relative to the workspace). Default <workspace>/artifacts/<slug>.",
|
|
46
|
+
},
|
|
47
|
+
url: { type: 'string', description: 'An artifact: open-artifact://artifact/<id>, as publish returned it.' },
|
|
48
|
+
files: {
|
|
49
|
+
type: 'object',
|
|
50
|
+
additionalProperties: true,
|
|
51
|
+
description: 'publish with url: files to write under the artifact root, as {"rel/path": "text"} or {"rel/path": {"content": "...", "encoding": "base64"}}; null deletes.',
|
|
52
|
+
},
|
|
53
|
+
if_match: {
|
|
54
|
+
type: 'object',
|
|
55
|
+
additionalProperties: true,
|
|
56
|
+
description: 'publish with url: {"rel/path": sha256 | null | "*"}. Write only while the file still has the sha256 you read, does not exist (null), or anyway ("*"). One mismatch writes nothing and returns the current versions.',
|
|
57
|
+
},
|
|
58
|
+
check: { type: 'boolean', description: "publish with url: run the type's check action after writing; its result comes back as check." },
|
|
59
|
+
open: {
|
|
60
|
+
type: 'string',
|
|
61
|
+
enum: ['after_first_write', 'now'],
|
|
62
|
+
description: "publish without url: after_first_write opens the page in your app once your first write lands; now opens it at once. Where your app cannot show pages by itself the result says so: open view_url in your app's built-in browser, if you have one.",
|
|
63
|
+
},
|
|
64
|
+
related: { type: 'boolean', description: 'quickstart: list existing artifacts the recommended type can build on, such as design systems (default true).' },
|
|
65
|
+
path: { type: 'string', description: 'read: one file or folder under the root (omitted: the record and the file list).' },
|
|
66
|
+
paths: { type: 'array', items: { type: 'string' }, description: 'read: several files under the root at once.' },
|
|
67
|
+
name: { type: 'string', description: "call: the action's name (check, upload, ...; read with url lists them)." },
|
|
68
|
+
args: { type: 'object', additionalProperties: true, description: "call: the action's arguments. upload: {file: absolute path, name?, group?}." },
|
|
69
|
+
panel: {
|
|
70
|
+
type: 'string',
|
|
71
|
+
enum: ARTIFACT_PANELS,
|
|
72
|
+
description: 'open: also open the page\'s Share panel (share), for the person to share it on the network, or its Export tab (export), for them to download a file.',
|
|
73
|
+
},
|
|
74
|
+
},
|
|
75
|
+
};
|
|
76
|
+
const DATA_SCHEMA = {
|
|
77
|
+
type: 'object',
|
|
78
|
+
properties: {
|
|
79
|
+
action: { type: 'string', enum: DATA_ACTIONS },
|
|
80
|
+
url: { type: 'string', description: 'The artifact (open-artifact://artifact/<id>).' },
|
|
81
|
+
collection: { type: 'string' },
|
|
82
|
+
doc_id: { type: 'string' },
|
|
83
|
+
path: { type: 'string', description: 'collection/doc_id, instead of the two.' },
|
|
84
|
+
data: { type: 'object', additionalProperties: true, description: "set / update: the document's fields." },
|
|
85
|
+
file_path: { type: 'string', description: 'set / update: a JSON file holding the fields, instead of data.' },
|
|
86
|
+
// No type: a sha256 string, or null.
|
|
87
|
+
if_match: {
|
|
88
|
+
description: 'set / update / delete / str_replace: the sha256 get returned (write only if unchanged), null (only if it does not exist) or "*" (replace whatever is there).',
|
|
89
|
+
},
|
|
90
|
+
field: { type: 'string', description: 'str_replace: the text field, as a dot path (body, notes.text).' },
|
|
91
|
+
old: { type: 'string', description: 'str_replace: the passage to replace; it must occur exactly once.' },
|
|
92
|
+
new: { type: 'string', description: 'str_replace: the passage that replaces it.' },
|
|
93
|
+
where: {
|
|
94
|
+
type: 'array',
|
|
95
|
+
items: { type: 'object', additionalProperties: true },
|
|
96
|
+
description: 'query: [{field, op, value}], all must hold. op: ==, !=, <, <=, >, >=, in, not-in (up to 30 values), array-contains.',
|
|
97
|
+
},
|
|
98
|
+
order_by: { type: 'object', additionalProperties: true, description: 'query: {field, dir: "asc" | "desc"}.' },
|
|
99
|
+
limit: { type: 'integer', description: 'list / query: how many documents (default 100, at most 1000).' },
|
|
100
|
+
cursor: { type: 'string', description: 'list / query: the next_cursor of the previous page.' },
|
|
101
|
+
out_file: { type: 'string', description: 'get / list / query: write the result to this JSON file (absolute, or relative to the workspace) and return only its path and counts.' },
|
|
102
|
+
writes: {
|
|
103
|
+
type: 'array',
|
|
104
|
+
items: { type: 'object', additionalProperties: true },
|
|
105
|
+
description: 'batch: [{op: set|update|delete|str_replace, path | collection+doc_id, data | file_path, if_match?, field?, old?, new?}], at most 500.',
|
|
106
|
+
},
|
|
107
|
+
},
|
|
108
|
+
required: ['action', 'url'],
|
|
109
|
+
};
|
|
110
|
+
const COMMENTS_SCHEMA = {
|
|
111
|
+
type: 'object',
|
|
112
|
+
properties: {
|
|
113
|
+
action: { type: 'string', enum: COMMENTS_ACTIONS },
|
|
114
|
+
url: { type: 'string', description: 'The artifact (open-artifact://artifact/<id>). wait: optional.' },
|
|
115
|
+
thread_id: { type: 'string', description: 'reply / resolve / reopen: the thread (after ";thread=" in the message).' },
|
|
116
|
+
text: { type: 'string', description: 'reply: the answer.' },
|
|
117
|
+
resolve: { type: 'boolean', description: 'reply: resolve the thread too.' },
|
|
118
|
+
all: { type: 'boolean', description: 'read: resolved threads too.' },
|
|
119
|
+
since: { type: 'string', description: 'read: only threads with a message at or after this time (ISO 8601).' },
|
|
120
|
+
acknowledge_duplicate: { type: 'boolean', description: 'reply: send the same text as your last reply in this thread again, on purpose.' },
|
|
121
|
+
timeout_ms: { type: 'number', description: 'wait: how long (default 600000).' },
|
|
122
|
+
},
|
|
123
|
+
required: ['action'],
|
|
124
|
+
};
|
|
125
|
+
/** The tools' argument schemas (JSON Schema). */
|
|
126
|
+
export const TOOL_SCHEMAS = {
|
|
127
|
+
Artifact: ARTIFACT_SCHEMA,
|
|
128
|
+
ArtifactData: DATA_SCHEMA,
|
|
129
|
+
ArtifactComments: COMMENTS_SCHEMA,
|
|
130
|
+
};
|
|
131
|
+
/** The tools' descriptions: what each action does and when to use it. Argument details are in the schemas. */
|
|
132
|
+
export const TOOL_DESCRIPTIONS = {
|
|
133
|
+
Artifact: [
|
|
134
|
+
'Make and change artifacts: typed folders of files that open as live pages the person can view, edit, comment on and export. Actions:',
|
|
135
|
+
'- quickstart {intent}: call first for a new artifact; recommends a type and returns the call that creates it.',
|
|
136
|
+
'- list {scope: "mine" | "all" | "types", type?, query?}: find existing artifacts, or the installed types.',
|
|
137
|
+
"- publish {type_url, title, folder?, open?}: create an artifact; the result carries its root folder and the type's instructions. publish {url, files, if_match?, check?}: write files when you have no file tools of your own.",
|
|
138
|
+
"- read {url, path? | paths?}: the artifact's record, files and actions, or some of its files with their sha256. read {type_url}: a type's instructions, before creating.",
|
|
139
|
+
'- open {url, panel?}: show it to the person in the computer\'s browser (or the app, when it shows pages), once its content is written. When your app has a built-in browser, open view_url there instead. panel "share" or "export" opens its Share panel or Export tab for them.',
|
|
140
|
+
"- call {url, name, args?}: run one of the type's actions (check, upload, ...). A long one answers {task, pending: true}; its result comes later as a message.",
|
|
141
|
+
'- adopt {url | folder}: take over an artifact, or add an existing folder. Only when the person asks.',
|
|
142
|
+
"- share {url}: whether it is shared on the local network, and its links. Only the person changes that, in the page's Share panel.",
|
|
143
|
+
'- delete {url}: forget an artifact; its folder stays. Only when the person asks.',
|
|
144
|
+
].join('\n'),
|
|
145
|
+
ArtifactData: 'Read and write the document store of an artifact whose type keeps one (its instructions say so). get, list and query read documents with their sha256; set, update, delete, str_replace and batch write them. update merges fields, and {"__delete__": true} removes one; str_replace changes one passage of a long text field. Replacing or deleting an existing document needs if_match: the sha256 you read, or "*". Your writes show live on open pages.',
|
|
146
|
+
ArtifactComments: 'Comments the person leaves on their artifact\'s page, kept in the artifact\'s own folder on this computer (no outside service). read lists the threads; reply answers one (thread_id is after ";thread=" in the message), with resolve: true when it is done; resolve and reopen change a thread\'s state. A thread sent to you is the person asking for your answer in it, so replying there is what they asked for. Answer only threads sent to you, in one or two lines. wait blocks until the next message for this session: use it only when nothing else can wake you.',
|
|
147
|
+
};
|
|
148
|
+
/**
|
|
149
|
+
* The tools' MCP annotations. All three work only on this computer's artifact folders, so none is open-world: an
|
|
150
|
+
* app's approval check (Cursor's auto-review) would otherwise take a comment reply for a write to an outside service.
|
|
151
|
+
*/
|
|
152
|
+
export const TOOL_ANNOTATIONS = {
|
|
153
|
+
Artifact: { title: 'Artifact', openWorldHint: false },
|
|
154
|
+
ArtifactData: { title: 'Artifact data', openWorldHint: false },
|
|
155
|
+
ArtifactComments: { title: 'Artifact comments', destructiveHint: false, openWorldHint: false },
|
|
156
|
+
};
|
|
157
|
+
/** Tool definitions in MCP shape. */
|
|
158
|
+
export const TOOL_DEFINITIONS = Object.keys(TOOL_SCHEMAS).map((name) => ({
|
|
159
|
+
name,
|
|
160
|
+
description: TOOL_DESCRIPTIONS[name],
|
|
161
|
+
inputSchema: TOOL_SCHEMAS[name],
|
|
162
|
+
annotations: TOOL_ANNOTATIONS[name],
|
|
163
|
+
}));
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The type server protocol: how the daemon starts and drives a local type
|
|
3
|
+
* server (`entry.start`), and the Type API (`/api/open-artifact.type.*`) the server
|
|
4
|
+
* calls back.
|
|
5
|
+
*
|
|
6
|
+
* Start-up:
|
|
7
|
+
*
|
|
8
|
+
* 1. The daemon runs `entry.start` in the type folder with the
|
|
9
|
+
* {@link TypeServerEnv} variables.
|
|
10
|
+
* 2. Within {@link READY_TIMEOUT_MS} the server prints one
|
|
11
|
+
* {@link ReadyLine} to stdout.
|
|
12
|
+
* 3. The daemon probes `GET /__open-artifact/health` every {@link HEALTH_INTERVAL_MS};
|
|
13
|
+
* after {@link HEALTH_MISSES} misses the server counts as stopped and is
|
|
14
|
+
* restarted with back-off, up to {@link MAX_RESTARTS} failures.
|
|
15
|
+
*
|
|
16
|
+
* Every `/__open-artifact/*` call carries `Authorization: Bearer <OPEN_ARTIFACT_SECRET>`.
|
|
17
|
+
*/
|
|
18
|
+
import type { WakeRequestItem, WakeStatus, WakeThread, WakeVia } from './wake.ts';
|
|
19
|
+
/** How long a type server has to print its ready line, ms. */
|
|
20
|
+
export declare const READY_TIMEOUT_MS = 15000;
|
|
21
|
+
/** Interval of health probes, ms. */
|
|
22
|
+
export declare const HEALTH_INTERVAL_MS = 30000;
|
|
23
|
+
/** Missed probes after which a server counts as stopped. */
|
|
24
|
+
export declare const HEALTH_MISSES = 3;
|
|
25
|
+
/** Failed starts after which the daemon gives up on a type server. */
|
|
26
|
+
export declare const MAX_RESTARTS = 5;
|
|
27
|
+
/** Environment variables the daemon passes to a type server. */
|
|
28
|
+
export interface TypeServerEnv {
|
|
29
|
+
/** Protocol version, `1`. */
|
|
30
|
+
OPEN_ARTIFACT_PROTOCOL: string;
|
|
31
|
+
/** Type id. */
|
|
32
|
+
OPEN_ARTIFACT_TYPE: string;
|
|
33
|
+
/** Absolute path of the type folder. */
|
|
34
|
+
OPEN_ARTIFACT_TYPE_DIR: string;
|
|
35
|
+
/** Port to listen on (`0`: pick one). */
|
|
36
|
+
OPEN_ARTIFACT_PORT: string;
|
|
37
|
+
/** Bearer secret of the `/__open-artifact/*` routes. */
|
|
38
|
+
OPEN_ARTIFACT_SECRET: string;
|
|
39
|
+
/** Base URL of the daemon. */
|
|
40
|
+
OPEN_ARTIFACT_DAEMON_URL: string;
|
|
41
|
+
/** Bearer token of the Type API. */
|
|
42
|
+
OPEN_ARTIFACT_TYPE_TOKEN: string;
|
|
43
|
+
/** Folder the server may keep state in. */
|
|
44
|
+
OPEN_ARTIFACT_STATE_DIR: string;
|
|
45
|
+
}
|
|
46
|
+
/** The line a type server prints to stdout once it listens. */
|
|
47
|
+
export interface ReadyLine {
|
|
48
|
+
openArtifact: 'ready';
|
|
49
|
+
/** Base URL of the server, e.g. `http://127.0.0.1:4721`. */
|
|
50
|
+
url: string;
|
|
51
|
+
}
|
|
52
|
+
/** `/__open-artifact/*` route paths on a type server. */
|
|
53
|
+
export declare const TYPE_SERVER_ROUTES: {
|
|
54
|
+
readonly health: "/__open-artifact/health";
|
|
55
|
+
readonly open: "/__open-artifact/open";
|
|
56
|
+
readonly close: "/__open-artifact/close";
|
|
57
|
+
readonly share: "/__open-artifact/share";
|
|
58
|
+
readonly actions: "/__open-artifact/actions/";
|
|
59
|
+
readonly summary: "/__open-artifact/summary";
|
|
60
|
+
readonly archive: "/__open-artifact/archive";
|
|
61
|
+
};
|
|
62
|
+
/** `GET /__open-artifact/health`. */
|
|
63
|
+
export interface TypeServerHealth {
|
|
64
|
+
openArtifact: 1;
|
|
65
|
+
type: string;
|
|
66
|
+
version?: string;
|
|
67
|
+
/** Artifacts with an open page. */
|
|
68
|
+
open?: number;
|
|
69
|
+
}
|
|
70
|
+
/** `POST /__open-artifact/open`: open (or find) the page of one artifact. */
|
|
71
|
+
export interface OpenRequest {
|
|
72
|
+
id: string;
|
|
73
|
+
/** Absolute path of the artifact folder. */
|
|
74
|
+
root: string;
|
|
75
|
+
title?: string;
|
|
76
|
+
/** Preferred UI language, e.g. `en` or `zh-CN`. */
|
|
77
|
+
lang?: string;
|
|
78
|
+
/** Origin of the Shell that will frame the page. */
|
|
79
|
+
shell?: string;
|
|
80
|
+
}
|
|
81
|
+
/** `POST /__open-artifact/open` answer. */
|
|
82
|
+
export interface OpenResult {
|
|
83
|
+
/** The page to frame (absolute, may carry a capability token). */
|
|
84
|
+
url: string;
|
|
85
|
+
/** The page without the Shell, when different. */
|
|
86
|
+
page_url?: string;
|
|
87
|
+
}
|
|
88
|
+
/** `POST /__open-artifact/close`. */
|
|
89
|
+
export interface CloseRequest {
|
|
90
|
+
id: string;
|
|
91
|
+
}
|
|
92
|
+
/** `POST /__open-artifact/share`: change LAN sharing. `GET /__open-artifact/share?id=` reads it. */
|
|
93
|
+
export interface ShareRequest {
|
|
94
|
+
id: string;
|
|
95
|
+
/** Open (`true`) or stop (`false`) sharing on the local network. */
|
|
96
|
+
lan?: boolean;
|
|
97
|
+
/** Turn each role's link on or off. */
|
|
98
|
+
links?: Partial<Record<ShareRole, boolean>>;
|
|
99
|
+
/** Roles whose link gets a new token: the old link stops working and the guests who joined with it are out. */
|
|
100
|
+
reset?: ShareRole[];
|
|
101
|
+
/** Guest id → a new role (its link must be on), or `null` to remove them. */
|
|
102
|
+
guests?: Record<string, ShareRole | null>;
|
|
103
|
+
}
|
|
104
|
+
/** A role a share link grants. */
|
|
105
|
+
export type ShareRole = 'editor' | 'commenter' | 'viewer';
|
|
106
|
+
/** Someone who joined through a share link. */
|
|
107
|
+
export interface ShareGuest {
|
|
108
|
+
id: string;
|
|
109
|
+
/** The name they typed when they joined. */
|
|
110
|
+
name: string;
|
|
111
|
+
role: ShareRole;
|
|
112
|
+
/** ISO time they joined. */
|
|
113
|
+
joined: string;
|
|
114
|
+
/** ISO time they were last seen. */
|
|
115
|
+
seen?: string;
|
|
116
|
+
/** They have the page open now. */
|
|
117
|
+
online: boolean;
|
|
118
|
+
/** Their link is on (and was not reset): `false` while it is off. */
|
|
119
|
+
active: boolean;
|
|
120
|
+
}
|
|
121
|
+
/** Sharing state of one artifact. */
|
|
122
|
+
export interface ShareView {
|
|
123
|
+
lan: boolean;
|
|
124
|
+
/** Addresses on the local network, when shared (a Tailscale address among them). */
|
|
125
|
+
addresses?: string[];
|
|
126
|
+
/** The port the links are on. */
|
|
127
|
+
port?: number;
|
|
128
|
+
links: Partial<Record<ShareRole, {
|
|
129
|
+
on: boolean;
|
|
130
|
+
url?: string;
|
|
131
|
+
}>>;
|
|
132
|
+
/** The people who joined: online or not, their link on or off. */
|
|
133
|
+
guests?: ShareGuest[];
|
|
134
|
+
/** The same links at this computer's Tailscale address (the roles whose link is on), for people on the tailnet. */
|
|
135
|
+
tailnet?: {
|
|
136
|
+
address: string;
|
|
137
|
+
links: Partial<Record<ShareRole, string>>;
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* `GET /__open-artifact/archive?id=`: the artifact's whole folder as one
|
|
142
|
+
* `.zip` (`Content-Disposition` names it), streamed; `HEAD` answers the same
|
|
143
|
+
* headers without zipping, or 413 `too_large` for a folder over what a plain
|
|
144
|
+
* zip holds (4 GiB, 65 535 files). The daemon passes it on as the Library
|
|
145
|
+
* API's `artifact.archive`.
|
|
146
|
+
*/
|
|
147
|
+
export declare const ARCHIVE_CONTENT_TYPE = "application/zip";
|
|
148
|
+
/**
|
|
149
|
+
* Reserved action names a server with `actions: true` may implement; the
|
|
150
|
+
* daemon uses them for the ArtifactData and ArtifactComments tools when the
|
|
151
|
+
* server owns those stores. Other names are the type's own (`check`,
|
|
152
|
+
* `upload`…). An unknown name answers 404 `unknown_action`.
|
|
153
|
+
*/
|
|
154
|
+
export declare const RESERVED_ACTIONS: readonly ["open-artifact.db.read", "open-artifact.db.write", "open-artifact.comments.read", "open-artifact.comments.reply", "open-artifact.comments.resolve"];
|
|
155
|
+
/** A reserved action name. */
|
|
156
|
+
export type ReservedAction = (typeof RESERVED_ACTIONS)[number];
|
|
157
|
+
/** `POST /__open-artifact/actions/<name>` body. */
|
|
158
|
+
export interface ActionRequest {
|
|
159
|
+
id: string;
|
|
160
|
+
root: string;
|
|
161
|
+
args: Record<string, unknown>;
|
|
162
|
+
}
|
|
163
|
+
/** `GET /__open-artifact/summary?id=`: a short text summary of an artifact for agents. */
|
|
164
|
+
export interface SummaryResult {
|
|
165
|
+
text: string;
|
|
166
|
+
}
|
|
167
|
+
/** Type API route names, after `/api/open-artifact.type.`. Bearer `OPEN_ARTIFACT_TYPE_TOKEN`, loopback only. */
|
|
168
|
+
export declare const TYPE_API_ROUTES: {
|
|
169
|
+
readonly artifact: "artifact";
|
|
170
|
+
readonly wake: "wake";
|
|
171
|
+
readonly presence: "presence";
|
|
172
|
+
readonly events: "events";
|
|
173
|
+
readonly touch: "touch";
|
|
174
|
+
readonly task: "task";
|
|
175
|
+
};
|
|
176
|
+
/** `GET /api/open-artifact.type.artifact?id=`. */
|
|
177
|
+
export interface TypeApiArtifact {
|
|
178
|
+
id: string;
|
|
179
|
+
url: string;
|
|
180
|
+
root: string;
|
|
181
|
+
title: string;
|
|
182
|
+
owner: {
|
|
183
|
+
label: string;
|
|
184
|
+
harness: string;
|
|
185
|
+
} | null;
|
|
186
|
+
agentName: string;
|
|
187
|
+
view_url: string;
|
|
188
|
+
}
|
|
189
|
+
/** `POST /api/open-artifact.type.wake`. */
|
|
190
|
+
export interface TypeApiWakeRequest {
|
|
191
|
+
id: string;
|
|
192
|
+
threads?: WakeThread[];
|
|
193
|
+
requests?: Array<Omit<WakeRequestItem, 'id'> & {
|
|
194
|
+
id?: string;
|
|
195
|
+
}>;
|
|
196
|
+
}
|
|
197
|
+
/** `POST /api/open-artifact.type.wake` answer. */
|
|
198
|
+
export interface TypeApiWakeResult {
|
|
199
|
+
status: WakeStatus;
|
|
200
|
+
via: WakeVia;
|
|
201
|
+
}
|
|
202
|
+
/** Whether an agent is there to receive. `GET /api/open-artifact.type.presence?id=`. */
|
|
203
|
+
export interface TypeApiPresence {
|
|
204
|
+
/** `online`: the owner's adapter is connected; `offline`: it is not; `none`: no owner. */
|
|
205
|
+
presence: 'online' | 'offline' | 'none';
|
|
206
|
+
canSend: boolean;
|
|
207
|
+
canSendSession: boolean;
|
|
208
|
+
busy: boolean;
|
|
209
|
+
agentName: string;
|
|
210
|
+
/** false: an idle owner session is not woken; what is sent waits for its next turn. Left out: it is woken. */
|
|
211
|
+
wakesIdle?: boolean;
|
|
212
|
+
}
|
|
213
|
+
/** Events of `GET /api/open-artifact.type.events?ids=<id,id>` (server-sent, `event:` is the type). */
|
|
214
|
+
export type TypeApiEvent = ({
|
|
215
|
+
type: 'presence';
|
|
216
|
+
id: string;
|
|
217
|
+
} & TypeApiPresence) | {
|
|
218
|
+
type: 'artifact';
|
|
219
|
+
id: string;
|
|
220
|
+
title?: string;
|
|
221
|
+
removed?: boolean;
|
|
222
|
+
};
|
|
223
|
+
/** `POST /api/open-artifact.type.touch`: the page wrote files. */
|
|
224
|
+
export interface TypeApiTouch {
|
|
225
|
+
id: string;
|
|
226
|
+
/** Who wrote: a viewer name or `agent`. */
|
|
227
|
+
author: string;
|
|
228
|
+
paths: string[];
|
|
229
|
+
/** New title, when the write changed it. */
|
|
230
|
+
title?: string;
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* `POST /api/open-artifact.type.task`: progress and end of a long action (one that
|
|
234
|
+
* answered `{task, pending: true}`). With `done`, the daemon hands `result`
|
|
235
|
+
* (or `error`) to the session that called the action, as a message that
|
|
236
|
+
* starts with {@link TASK_HEADER}.
|
|
237
|
+
*/
|
|
238
|
+
export interface TypeApiTask {
|
|
239
|
+
task: string;
|
|
240
|
+
done?: boolean;
|
|
241
|
+
/** 0 to 1; logged only. */
|
|
242
|
+
progress?: number;
|
|
243
|
+
/** With `done`: what the action returns. */
|
|
244
|
+
result?: unknown;
|
|
245
|
+
/** With `done`: why it failed. */
|
|
246
|
+
error?: string | {
|
|
247
|
+
code: string;
|
|
248
|
+
message: string;
|
|
249
|
+
fix?: string;
|
|
250
|
+
};
|
|
251
|
+
}
|