@coda-console/plugin-check 0.8.22 → 0.8.24

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.
@@ -0,0 +1,362 @@
1
+ // Coda's own protocols of its workflows, as data: `coda/workflow@1`, `coda/workflow-run@1` and the query of `coda/thread@1` they
2
+ // answer (`withWorkflows`), each a definition and the schemas it is made of (./workflow-protocols.mjs says what they are and
3
+ // gives their records). Nothing here runs: application/host-protocols.mjs lists them for the backend and the plugin host for
4
+ // a plugin's tests (adapters/plugin-test-host.mjs) alike.
5
+ import { INPUT_SOURCES, INPUT_TYPES } from '@coda-console/protocol/workflow';
6
+ import { derivedUUID } from '../../domain/values.mjs';
7
+
8
+ // A text input's length: room for what one workflow hands another, such as release notes (`run-workflows`), for a
9
+ // command the user is asked to approve, as long as its card takes (`approve-command`, components/workflows/task-fields.mjs),
10
+ // and for a task's note (workflow-tasks.mjs), which a process may take as such a text: release notes, an executor's next task.
11
+ export const INPUT_LIMIT = 16 * 1024;
12
+ // The most a run's requirement says (`run.message`): what a message takes (store acceptMessage).
13
+ export const MESSAGE_LIMIT = 100_000;
14
+
15
+ export const WORKFLOW = 'coda/workflow@1';
16
+ // Coda's sessions, whose directory's workflows are a query of theirs these answer (`withWorkflows`).
17
+ export const THREAD = 'coda/thread@1';
18
+ export const WORKFLOW_RUN = 'coda/workflow-run@1';
19
+ // A workflow's record is named by its directory and its name: the same workflow of the same directory is the same record
20
+ // on every reading. A run's record is named by the run's ID.
21
+ export const workflowRecordId = (project, workflow) => derivedUUID(WORKFLOW, project, workflow);
22
+
23
+ export const object = (properties, required = [], rest = {}) =>
24
+ ({ type: 'object', properties, ...(required.length ? { required } : {}), additionalProperties: false, ...rest });
25
+ export const list = items => ({ type: 'array', items });
26
+ const text = { type: 'string', minLength: 1 };
27
+ const flag = { type: 'boolean' };
28
+ const count = { type: 'integer', minimum: 0 };
29
+ export const time = { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$' };
30
+ const timeOrNull = { ...time, type: ['string', 'null'] };
31
+ const textOrNull = { ...text, type: ['string', 'null'] };
32
+ // A workflow's file name, without `.bpmn` (components/workflows/workflow.mjs workflowName).
33
+ const workflowName = { type: 'string', pattern: '^[a-z][a-z0-9-]{0,39}$' };
34
+ const SOURCES = Object.keys(INPUT_SOURCES);
35
+
36
+ // An Agent combination, the value of an `agent` input (session-config/contributions.mjs `coda-agent`).
37
+ const AGENT = object({
38
+ agent: { type: 'string', pattern: '^[a-z][a-z0-9-]{0,39}$' },
39
+ model: text, effort: text, mode: text,
40
+ options: { type: 'object', additionalProperties: { anyOf: [flag, { type: 'string', minLength: 1, maxLength: 200 }] } },
41
+ }, ['agent']);
42
+ // A value given for an input, of its declared type; a run's own inputs, as resolved, leave an `agent` one with none null.
43
+ const VALUE = { anyOf: [{ type: 'string', maxLength: INPUT_LIMIT }, { type: 'number' }, flag, AGENT] };
44
+ const RESOLVED = { anyOf: [...VALUE.anyOf, { type: 'null' }] };
45
+ // An input as the workflow declares it (`coda:input`, components/workflows/bpmn.mjs).
46
+ const INPUT = {
47
+ type: { enum: INPUT_TYPES }, label: text, description: text, required: flag,
48
+ defaultFrom: { enum: SOURCES }, default: { type: ['string', 'number', 'boolean'] },
49
+ };
50
+ // Where an input takes its value from when a run is given none: a value, or a source of the session it starts from.
51
+ const RULE = { oneOf: [object({ value: VALUE }, ['value']), object({ from: { enum: SOURCES } }, ['from'])] };
52
+ // What the sources give in a session now (INPUT_SOURCES): its branch, its Agent combination.
53
+ const SOURCE_VALUES = object(Object.fromEntries(Object.entries(INPUT_SOURCES)
54
+ .map(([name, { types }]) => [name, types.includes('agent') ? AGENT : text])));
55
+
56
+ // The outputs a step or a run gives (a step's `$GITHUB_OUTPUT`, the end event's `coda:output`).
57
+ const OUTPUTS = { type: 'object', additionalProperties: { type: ['string', 'number', 'boolean', 'null'] } };
58
+ const RUN_STATE = { enum: ['waiting', 'running', 'cancelling', 'succeeded', 'failed', 'cancelled'] };
59
+ // A step's attempt, or `pending` / `skipped` for one this round has not reached.
60
+ const JOB_STATE = { enum: ['pending', 'queued', 'running', 'succeeded', 'failed', 'cancelled', 'skipped'] };
61
+
62
+ // What the user, a session or its project set for a workflow (components/workflows/workflow-settings.mjs), as a session
63
+ // sees it: whether the events that start it by themselves do (only for one they start, `startedBy`), each input's rule
64
+ // and the value it would take now, and where each comes from (`SEEN`); and what the session's sources give now.
65
+ export const SEEN = {
66
+ enabled: object({ value: flag, source: { enum: ['session', 'project', 'plugin', 'template'] } }, ['value', 'source']),
67
+ inputs: list(object({ name: text, ...INPUT, rule: RULE, source: { enum: ['session', 'project', 'template'] }, value: RESOLVED },
68
+ ['name', 'type', 'source', 'value'])),
69
+ };
70
+ export const SETTINGS = object({ ...SEEN, sources: SOURCE_VALUES }, ['inputs', 'sources']);
71
+
72
+ // A run as it stands (workflow_status of one run, components/workflows/workflow-run-records.mjs `describe`): its state and
73
+ // round (`attempt`), what its card says (title, line, stages, the messages from the user it waits on), whether a resume
74
+ // goes on where it failed (`rerun`), its place in the queue, its workspace's retention, its times, how it ended, each step
75
+ // with its attempt and that attempt's steps and sessions, each user task of the round, and the runs it called. What a task
76
+ // asks (its choices, fields) is on its card; a step's log is read as the stream `log`, not by a path on the machine that ran it.
77
+ export const STEP = object({
78
+ index: count, name: text,
79
+ state: { enum: ['pending', 'running', 'success', 'failure', 'cancelled', 'skipped'] },
80
+ conclusion: { enum: [null, 'success', 'failure', 'cancelled', 'skipped'] },
81
+ // How it went before `continue-on-error` made a failure its conclusion's success.
82
+ outcome: { enum: [null, 'success', 'failure', 'cancelled', 'skipped'] },
83
+ exitCode: { type: ['integer', 'null'] }, startedAt: timeOrNull, finishedAt: timeOrNull,
84
+ }, ['index', 'name', 'state', 'conclusion', 'exitCode', 'startedAt', 'finishedAt']);
85
+ export const JOB = object({
86
+ job: text, name: text, needs: list(text), group: text, state: JOB_STATE,
87
+ // Its current attempt, 0 before the first; the commit, error and outputs of that attempt.
88
+ attempt: count, commit: textOrNull, error: { type: ['string', 'null'] }, outputs: OUTPUTS,
89
+ queuedAt: timeOrNull, startedAt: timeOrNull, finishedAt: timeOrNull,
90
+ // The line it is at while it runs, and why and until when its agent is held up, the how-manieth time.
91
+ step: text, blocked: object({ reason: text, until: time, attempt: { type: 'integer', minimum: 1 } }, ['reason', 'until', 'attempt']),
92
+ steps: list(STEP),
93
+ // The sessions its `coda-agent` steps started, every attempt's.
94
+ agents: list(object({ session: text, title: { type: 'string' }, agent: text, model: text, effort: text,
95
+ step: { type: ['integer', 'null'], minimum: 0 }, attempt: { type: 'integer', minimum: 1 } }, ['session', 'title', 'agent', 'attempt'])),
96
+ // Every attempt of it whose history is kept, oldest first: how each went and ended.
97
+ attempts: list(object({ attempt: { type: 'integer', minimum: 1 }, state: JOB_STATE, startedAt: timeOrNull, finishedAt: timeOrNull,
98
+ error: { type: ['string', 'null'] } }, ['attempt', 'state', 'startedAt', 'finishedAt', 'error'])),
99
+ // Its attempts' logs reclaimed past their retention.
100
+ logsPruned: flag,
101
+ // Its current attempt's sessions wait on a card of theirs, the run then held up by the user, not by its work.
102
+ agentNeedsInput: { const: true },
103
+ }, ['job', 'name', 'needs', 'state', 'attempt', 'steps', 'agents']);
104
+ // An answer a user task offers (components/workflows/bpmn.mjs parseChoices).
105
+ const CHOICE_FACTS = { id: text, name: text, detail: { type: 'string' }, primary: { const: true }, note: { const: 'required' }, fields: list(text),
106
+ options: list({ type: 'object' }) };
107
+ const CHOICE = object({ ...CHOICE_FACTS, more: list(object(CHOICE_FACTS, ['id', 'name'])) }, ['id', 'name']);
108
+ // A user task of this round: whom an open one waits on (`agent`, `input` the user) since when, its ID (what `task` answers),
109
+ // its card while open and the answers it offers (`choices`, as the process declares them: `more` held one level down), whether
110
+ // its card has fields to fill (`form`, answered there), whether its holding session is told of it only with its next input
111
+ // (`toldAlong`); what it asks the agent (`instructions`, not said of one for the user); how a decided one was.
112
+ export const TASK = object({
113
+ step: text, name: text, state: { enum: ['pending', 'skipped', 'agent', 'input', 'succeeded', 'failed', 'cancelled'] },
114
+ task: text, assignee: { enum: ['agent', 'user'] }, holder: text, card: text, since: time, choices: list(CHOICE), form: { const: true },
115
+ toldAlong: { const: true }, instructions: text,
116
+ startedAt: time, finishedAt: timeOrNull, decidedBy: text, note: text,
117
+ }, ['step', 'name', 'state']);
118
+ // Where a node, or an instance of it, stands this round, as its kind, its step or its task says (workflow-graph.mjs `shown`).
119
+ const NODE_STATE = { enum: ['pending', 'queued', 'running', 'waiting', 'agent', 'input', 'finishing', 'succeeded', 'failed', 'cancelled', 'skipped'] };
120
+ // What a node of the process is (workflow-graph.mjs `bpmnGraph`): an event node by its event (a caught error is `boundary`).
121
+ const NODE_KIND = { enum: ['start', 'end', 'event', 'job', 'action', 'task', 'call', 'manual', 'step', 'subprocess', 'gateway', 'boundary',
122
+ 'timer', 'message', 'signal', 'conditional', 'escalation', 'link', 'compensation', 'cancel'] };
123
+ // Where the run is while it goes (workflowGraph `current`): each instance going that nothing else goes inside, since when,
124
+ // and when one waiting on a timer is due.
125
+ export const PLACE = object({ node: text, executionId: text, name: text, kind: NODE_KIND, parent: text, state: NODE_STATE, since: time, dueAt: time },
126
+ ['node', 'name', 'kind', 'state', 'since']);
127
+ // An event it listens for meanwhile, no instance of its node until it happens (workflowGraph `listening`): a boundary
128
+ // event beside an activity (`attachedTo`), one an event-based gateway races, a start event of an event subprocess; by
129
+ // its kind, the message it waits for or the timer it is set to and when that is due, since when it listens.
130
+ export const LISTENING = object({ node: text, executionId: text, name: text, kind: NODE_KIND, parent: text, attachedTo: text,
131
+ message: text, timer: text, since: time, dueAt: time }, ['node', 'name', 'kind']);
132
+ // The runs a node called (`run-workflows`, a call activity).
133
+ export const CALLED = list(object({ run: text, workflow: workflowName, name: text, state: RUN_STATE }, ['run', 'workflow', 'name', 'state']));
134
+ // The whole drawing of the run (`graph`): each node as the process declares it (`bpmnGraph`) with where it stands this
135
+ // round (its latest instance, how many and how they ended, whether it is only listened for, the line it shows), each flow
136
+ // with how often it was taken, and where the run is. A node's step or task is the status's job of the same id.
137
+ export const GRAPH = object({
138
+ nodes: list(object({
139
+ id: text, name: text, kind: NODE_KIND, type: text,
140
+ triggeredByEvent: { const: true }, throw: { const: true }, eventGateway: text, interrupting: { const: false },
141
+ loop: { enum: ['sequential', 'parallel'] }, forCompensation: { const: true }, lane: text,
142
+ inspect: list(object({ label: text, type: { enum: ['string', 'number', 'boolean', 'timestamp'] }, value: text, phase: { enum: ['input', 'output'] } },
143
+ ['label', 'type', 'value', 'phase'])),
144
+ parent: text, attachedTo: text, group: text, action: text, message: text, timer: text,
145
+ state: NODE_STATE, visits: count, counts: object({ active: count, succeeded: count, failed: count, cancelled: count }, ['active', 'succeeded', 'failed', 'cancelled']),
146
+ executionId: text, startedAt: time, finishedAt: time, dueAt: time, listener: { const: true }, detail: text, since: time, called: CALLED,
147
+ }, ['id', 'name', 'kind', 'type', 'state'])),
148
+ edges: list(object({ id: text, from: text, to: text, name: text, default: { const: true }, boundary: { const: true }, link: { const: true },
149
+ compensation: { const: true }, taken: count }, ['id', 'from', 'to'])),
150
+ current: list(PLACE), listening: list(LISTENING),
151
+ }, ['nodes', 'edges', 'current', 'listening']);
152
+ // A round the run went (its first, then each resume or re-run): for which session it was, if any, by the user or not, and
153
+ // where in that session's history it started and ended (`startedAfterSeq`, `afterSeq`); whether its end is told (`reportResult`),
154
+ // whether it went on where the last failed (`resumed`), and how it ended.
155
+ export const ROUND = object({ session: text, startedAt: time, startedAfterSeq: { type: ['integer', 'null'] }, byUser: { const: true }, reportResult: flag,
156
+ resumed: { const: true }, state: RUN_STATE, endedAt: time, afterSeq: { type: ['integer', 'null'] } }, ['startedAt']);
157
+ export const RUN_STATUS = object({
158
+ state: RUN_STATE, attempt: { type: 'integer', minimum: 1 }, rounds: list(ROUND),
159
+ // Where it is and what it listens for, while it goes (empty once it ended); the whole drawing is `graph`'s.
160
+ current: list(PLACE), listening: list(LISTENING),
161
+ // `lineLive`: whether the step that wrote the line still runs; once it ended, the line stays and says so.
162
+ title: text, line: text, lineLive: flag,
163
+ stages: list(object({ id: text, name: text, state: { enum: ['pending', 'running', 'agent', 'input', 'succeeded', 'failed', 'cancelled', 'skipped'] } },
164
+ ['id', 'name', 'state'])),
165
+ messages: list(object({ name: { type: 'string', pattern: '^user\\.' }, label: text }, ['name', 'label'])),
166
+ // The steps for the user's eyes only (`coda:audience="user"`), not among `jobs`: the user's page reads them with `private`.
167
+ userOnly: list(text),
168
+ cancelRequested: { const: true }, rerun: { enum: ['resume', 'start', 'caller'] }, ahead: count,
169
+ workspace: object({ state: { enum: ['active', 'retained', 'reclaimed'] }, cleanupAfter: timeOrNull, reclaimedAt: timeOrNull },
170
+ ['state', 'cleanupAfter', 'reclaimedAt']),
171
+ createdAt: time, startedAt: timeOrNull, finishedAt: timeOrNull,
172
+ // How it ended: what went wrong, what it gives, and the outcome told to whoever started it.
173
+ error: text, outputs: OUTPUTS, result: text,
174
+ jobs: list(JOB), tasks: list(TASK),
175
+ called: CALLED,
176
+ // A text that changes as what `requirement` gives does (the runs under it moving among it), for a page to ask it again by.
177
+ requirementRevision: text,
178
+ }, ['state', 'attempt', 'current', 'listening', 'createdAt', 'startedAt', 'finishedAt', 'jobs', 'tasks', 'called'],
179
+ { dependentRequired: { line: ['lineLive'] } });
180
+
181
+ // A node's instances in this round, newest last, a page at a time (components/workflows/workflow-run-records.mjs
182
+ // `nodeHistory`): each with what it was given and gave, the conditions it took its way by, the attempt or task it was and
183
+ // the runs it called. `next` is the `before` of the page before it, null at the first.
184
+ const FIELD = object({ label: text, type: text, source: text, value: { type: ['string', 'number', 'boolean'] },
185
+ missing: { const: true }, truncated: { const: true }, sourceLabel: text }, ['source']);
186
+ const INSTANCE = object({
187
+ executionId: text, ordinal: count, parent: text, iteration: { type: ['integer', 'null'] },
188
+ state: NODE_STATE,
189
+ startedAt: time, endedAt: timeOrNull, dueAt: timeOrNull,
190
+ inputs: list(FIELD), outputs: list(FIELD),
191
+ conditions: list(object({ id: text, name: text, expression: text, inputs: list(FIELD), label: text, default: flag, error: text, result: flag }, ['id'])),
192
+ taken: list(text), error: text,
193
+ attempt: object({ attempt: { type: 'integer', minimum: 1 }, state: JOB_STATE, queuedAt: timeOrNull, startedAt: timeOrNull,
194
+ finishedAt: timeOrNull, error: text }, ['attempt', 'state']),
195
+ task: object({ state: { enum: ['open', 'completed', 'rejected', 'withdrawn'] }, assignee: { enum: ['agent', 'user'] }, decidedBy: text, note: text },
196
+ ['state', 'assignee']),
197
+ called: list(object({ run: text, workflow: workflowName, state: RUN_STATE }, ['run', 'workflow', 'state'])),
198
+ }, ['executionId', 'state', 'startedAt']);
199
+ const HISTORY = object({ instances: list(INSTANCE), retainedInstances: count, historyPruned: flag,
200
+ next: { type: ['integer', 'null'], minimum: 1 } }, ['instances', 'retainedInstances', 'historyPruned', 'next']);
201
+ // The requirement the run was started for (components/workflows/workflow-run-records.mjs `requirement`): its words, every run
202
+ // under it (each by the node of its caller that called it and that caller's round), the sessions its steps and its own agent
203
+ // are, and the user tasks of those runs — each kept to its share of the bytes, `truncated` saying which was cut.
204
+ const REQUIREMENT = object({
205
+ message: { type: 'string' },
206
+ truncated: object({ message: flag, runs: flag, sessions: flag, tasks: flag }, ['message', 'runs', 'sessions', 'tasks']),
207
+ runs: list(object({ run: text, workflow: workflowName, name: text, state: RUN_STATE, error: text, createdAt: time, startedAt: timeOrNull, finishedAt: timeOrNull,
208
+ parent: text, node: object({ id: text, name: text }, ['id', 'name']), round: { type: 'integer', minimum: 1 }, callerRound: { type: 'integer', minimum: 1 },
209
+ outputs: OUTPUTS }, ['run', 'workflow', 'name', 'state', 'createdAt', 'startedAt', 'finishedAt', 'outputs'])),
210
+ sessions: list(object({ session: text, title: { type: 'string' }, agent: text, archived: flag,
211
+ role: object({ main: { const: true }, run: text, node: text, name: text, attempt: { type: 'integer', minimum: 1 }, step: { type: ['integer', 'null'], minimum: 0 } }, ['run']) },
212
+ ['session', 'title', 'agent', 'archived', 'role'])),
213
+ tasks: list(object({ task: text, run: text, round: { type: 'integer', minimum: 1 }, node: text, name: text, state: { enum: ['open', 'completed', 'rejected', 'withdrawn'] },
214
+ assignee: { enum: ['agent', 'user'] }, turn: { enum: ['agent', 'user'] }, holder: text, decidedBy: text, choice: object({ id: text, name: text }, ['id', 'name']),
215
+ note: text, createdAt: time, decidedAt: timeOrNull }, ['task', 'run', 'round', 'node', 'name', 'state', 'assignee', 'createdAt', 'decidedAt'])),
216
+ }, ['message', 'truncated', 'runs', 'sessions', 'tasks']);
217
+ // How each of its jobs ended in the latest runs of its workflow in its directory that ended, up to it, oldest first; null in
218
+ // one a job did not run in.
219
+ const RECENT = object({ jobs: list(object({ job: text, history: list({ enum: [...JOB_STATE.enum, null] }) }, ['job', 'history'])) }, ['jobs']);
220
+
221
+ export const WORKFLOW_PROTOCOL = {
222
+ kind: WORKFLOW,
223
+ title: '流程',
224
+ // What the workflow is, as `workflow_list` gives each (components/workflows/workflow-definitions.mjs `list`): of which
225
+ // directory and by which name, a plugin's when a plugin brings it (and the directory has no file of that name), a
226
+ // capability when it is only called; read from the directory's default branch as last fetched, or the plugin. Its
227
+ // inputs, whether it runs only merged commits, whether it can be started by hand, the hooks it joins, the events that
228
+ // start it by themselves, its schedule, its key, its `coda:autoRun`, whether it follows sessions from their opening;
229
+ // or, for one that cannot be read, why (`error`) instead.
230
+ // No `runsOn`: the executors are gone (结构减负), and `listed()` no longer gives the labels a workflow's steps need.
231
+ spec: object({
232
+ project: text, workflow: workflowName, plugin: text, capability: { const: true },
233
+ name: text, inputs: { type: 'object', additionalProperties: object(INPUT, ['type']) },
234
+ mergedOnly: flag, manual: flag,
235
+ joins: list(object({ hook: text, name: text, detail: text, default: flag, order: { type: 'number' },
236
+ inputs: list(object({ id: text, label: text }, ['id', 'label'])) }, ['hook', 'default'])),
237
+ startedBy: list(text), schedule: object({ cycle: text, once: flag }, ['cycle', 'once']),
238
+ key: text, autoRun: text, lifecycle: { const: true },
239
+ error: text,
240
+ }, ['project', 'workflow'], { oneOf: [{ required: ['error'] }, { required: ['name', 'inputs', 'mergedOnly', 'manual'] }] }),
241
+ // What changes of it in its directory: the branch and commit it was read from (none for a plugin's), what was set for
242
+ // it in the directory, its schedule there (when it next starts, or why it does not), the events it starts on that
243
+ // nothing here publishes, and the plugins that bring the same name when two do (it is refused until one is disabled).
244
+ status: object({
245
+ ref: text, commit: text,
246
+ settings: object({ enabled: flag, inputs: { type: 'object', additionalProperties: RULE } }, ['inputs']),
247
+ schedule: object({ cycle: text, next: timeOrNull, off: { const: true }, error: text, project: text }, ['cycle']),
248
+ unheard: list(text), conflicts: list(text),
249
+ }, ['settings']),
250
+ operations: {
251
+ // Starts it from `session`, as the session's "+" does (`workflow_run`, as the user's): on the newest commit of the
252
+ // session's branch, with `inputs` (the rest as the session sets them, else as declared) and `message`, the requirement
253
+ // it goes with, sent into the session as the user's message. A call here has no session of its own: no `commit`, and
254
+ // no `confirm`: the card only a session's agent can propose (its workflow tool's own arguments), and this way does not take it.
255
+ run: { input: object({
256
+ session: text, inputs: { type: 'object', additionalProperties: VALUE }, message: { type: 'string', maxLength: MESSAGE_LIMIT },
257
+ }, ['session']),
258
+ result: object({ run: text, status: RUN_STATUS, reused: { const: true } }, ['run', 'status']) },
259
+ // What is set for it as `session` sees it, or as set for its directory without one.
260
+ settings: { safe: true, input: object({ session: text }), result: SETTINGS },
261
+ // Sets it, from `session`, for the session alone or for its directory (`project`): whether the events that start it do
262
+ // (`enabled`, null goes back to what comes after) and its inputs' rules (null clears one). Set for the directory, the
263
+ // session drops its own of what was set, following its directory. Gives what `settings` gives after, for the session.
264
+ 'save-settings': { idempotent: true, input: object({
265
+ scope: { enum: ['session', 'project'] }, session: text, enabled: { type: ['boolean', 'null'] },
266
+ inputs: { type: 'object', additionalProperties: { anyOf: [RULE, { type: 'null' }] } },
267
+ }, ['scope', 'session']), result: SETTINGS },
268
+ },
269
+ // What a plugin may ask for in its `uses` (docs/plugins.md「用到的权限」), on trial while the protocol is not stable.
270
+ permissions: {
271
+ read: { title: '查看各目录里可用的流程与它们的设置', trial: true, read: true, operations: ['settings'] },
272
+ run: { title: '发起流程', trial: true, operations: ['run'] },
273
+ configure: { title: '修改流程在会话或目录里的设置', trial: true, operations: ['save-settings'] },
274
+ },
275
+ // Its doing operations are the workflows', on the backend that holds the record (`workflowOperations`).
276
+ side: 'workflows',
277
+ };
278
+
279
+ // The workflows of a session's directory, as its workflows panel reads them as it opens (#2749 3.5: what a panel takes at
280
+ // once is one query of the record it is of): a query of `coda/thread@1` the workflows answer, added to it as it is
281
+ // registered (`withWorkflows`). Each workflow the user may start there, or an event may (not a capability, which is called,
282
+ // nor a lifecycle, which follows sessions, nor one only a schedule starts): its record's ID and what it is, and what is set
283
+ // for it as the session sees it (not for one that cannot be read); what the session's sources give now; and why the
284
+ // directory's own could not be read, when they could not (no `origin/main`, no repository: `error`), so that none read is
285
+ // not none there; a plugin's, which plugin by its name. A group of its own, not `read`'s: it says what is set.
286
+ export const THREAD_WORKFLOWS = {
287
+ safe: true, input: object({}),
288
+ result: object({
289
+ project: text,
290
+ workflows: list(object({ id: text, spec: WORKFLOW_PROTOCOL.spec, plugin: object({ id: text, name: text }, ['id', 'name']), settings: object(SEEN, ['inputs']) }, ['id', 'spec'])),
291
+ sources: SOURCE_VALUES, error: text,
292
+ }, ['project', 'workflows', 'sources']),
293
+ };
294
+ export const withWorkflows = protocol => ({ ...protocol, operations: { ...protocol.operations, workflows: THREAD_WORKFLOWS },
295
+ permissions: { ...protocol.permissions, workflows: { title: '查看会话的目录里能发起的流程,以及它们在这个会话里的设置', trial: true, operations: ['workflows'] } } });
296
+
297
+ export const WORKFLOW_RUN_PROTOCOL = {
298
+ kind: WORKFLOW_RUN,
299
+ title: '流程运行',
300
+ // Where the run comes from: the workflow of which directory (its record `workflowRecordId(project, workflow)`), a
301
+ // plugin's or a capability, under which name; the commit and branch it runs on (none for a plugin's that checks nothing
302
+ // out; a resume with `commit` moves it), the inputs it was started with as resolved, the requirement it goes with, its
303
+ // key; and who started it (`origin`): an agent, the user, an event, a schedule or another run (`parent`), for which
304
+ // session (`session`, whom it reports to), and for a session's lifecycle, the session it follows (`subject`).
305
+ spec: object({
306
+ project: text, workflow: workflowName, plugin: text, capability: { const: true }, name: text,
307
+ commit: textOrNull, ref: textOrNull,
308
+ inputs: { type: 'object', additionalProperties: RESOLVED },
309
+ message: { type: 'string', maxLength: MESSAGE_LIMIT }, key: text,
310
+ origin: object({ by: { enum: ['agent', 'user', 'event', 'schedule', 'run'] }, session: text, parent: text, event: text, subject: text }, ['by']),
311
+ }, ['project', 'workflow', 'name', 'commit', 'ref', 'inputs', 'origin']),
312
+ status: RUN_STATUS,
313
+ operations: {
314
+ // Cancels a run waiting or going (`workflow_cancel`); renews a failed or cancelled one's workspace and artifacts for
315
+ // another stretch from now (`workflow_renew`); resumes a failed or cancelled one (`workflow_resume`): where it failed,
316
+ // or from its start (`from`), on its commit, on `commit`, or on the newest commit of its branch (`latest`). Each
317
+ // gives the run as it stands after.
318
+ cancel: { input: object({}), result: RUN_STATUS },
319
+ renew: { input: object({}), result: RUN_STATUS },
320
+ resume: { input: object({ commit: text, from: { type: 'string', enum: ['start'] }, latest: { const: true } }, [], { not: { required: ['commit', 'latest'] } }),
321
+ result: RUN_STATUS },
322
+ // Answers a task the run gave the caller's session (`workflow_task`), which only the task's holder may — a caller that
323
+ // is no session (the user, through a plugin's page), one that waits on the user —: `completed` with the `choice`
324
+ // taken, its `options` and their `inputs`, or `rejected`, with `note`; or hands it up (`handUp`) to the level above,
325
+ // with what is to be done in `note`, which only a session does.
326
+ task: { input: object({
327
+ task: text, result: { type: 'string', enum: ['completed', 'rejected'] }, handUp: flag, choice: text,
328
+ options: { type: 'object', additionalProperties: flag },
329
+ inputs: { type: 'object', additionalProperties: { type: 'string', maxLength: INPUT_LIMIT } },
330
+ note: { type: 'string', maxLength: INPUT_LIMIT },
331
+ }, ['task'], { if: { properties: { handUp: { const: true } }, required: ['handUp'] }, then: { required: ['note'] }, else: { required: ['result'] } }),
332
+ result: object({ task: text, name: text, result: { enum: ['completed', 'rejected'] }, choice: text, handedUp: { const: true } }, ['task', 'name'],
333
+ { oneOf: [{ required: ['result'] }, { required: ['handedUp'] }] }) },
334
+ // A message from the user that the run waits on (one of its status's `messages`), as its page's button sends it.
335
+ message: { input: object({ name: { type: 'string', pattern: '^user\\.' } }, ['name']), result: RUN_STATUS },
336
+ // A page of a node's instances in this round, before `before` (a page's `next`), the latest without.
337
+ history: { safe: true, input: object({ node: text, before: { type: 'integer', minimum: 1 } }, ['node']), result: HISTORY },
338
+ // The whole drawing of the run as it stands, for its page to draw.
339
+ graph: { safe: true, input: object({}), result: GRAPH },
340
+ // The requirement it was started for, with the runs under it, their sessions and tasks; asked again as its status's
341
+ // `requirementRevision` changes.
342
+ requirement: { safe: true, input: object({}), result: REQUIREMENT },
343
+ // Its jobs' results in the latest runs of its workflow in its directory.
344
+ recent: { safe: true, input: object({}), result: RECENT },
345
+ // Its steps for the user's eyes only (its status's `userOnly`), as the user's page shows them: refused to a session.
346
+ private: { safe: true, input: object({}), result: object({ jobs: list(JOB) }, ['jobs']) },
347
+ },
348
+ // A step's output as it is (`text/plain`), from byte `after` to its end as it is read, not cut and not followed: step `step`
349
+ // of the job, or the job's own log (`job`), of its current attempt or of `attempt` (transport/record-streams.mjs). Read on
350
+ // from where it was (`after`, the bytes read), the attempt is named, so that one begun meanwhile is not read on.
351
+ streams: {
352
+ log: { input: object({ job: text, step: { type: 'string', pattern: '^(?:[0-9]+|job)$' }, attempt: { type: 'string', pattern: '^[1-9][0-9]*$' },
353
+ after: { type: 'string', pattern: '^[0-9]+$' } }, ['job', 'step']) },
354
+ },
355
+ permissions: {
356
+ read: { title: '查看流程运行:进度、流程图、步骤、节点历史、日志、需求与最近的结果', trial: true, read: true,
357
+ operations: ['history', 'graph', 'requirement', 'recent', 'private'], streams: ['log'] },
358
+ control: { title: '取消、续期、重跑流程运行,或替你点运行在等的按钮', trial: true, operations: ['cancel', 'renew', 'resume', 'message'] },
359
+ task: { title: '答复流程交给会话的任务', trial: true, operations: ['task'] },
360
+ },
361
+ side: 'workflows',
362
+ };
@@ -1,24 +1,27 @@
1
1
  {
2
- "commit": "8ff481af89b9da86e09a5af2134884c78da0a011",
2
+ "commit": "ca6267e229bcf0c622187c6cd300022d59505203",
3
3
  "packages": {
4
4
  "@0dep/piso": "5.2.0",
5
5
  "@agentclientprotocol/sdk": "2.6.0",
6
- "@coda-console/protocol": "6.13.0",
6
+ "@coda-console/protocol": "6.15.0",
7
7
  "ajv": "8.20.0",
8
8
  "yaml": "2.9.1"
9
9
  },
10
10
  "files": {
11
11
  "check/coda/application/contributions.mjs": "861c363d06cdabfc4ce15435126fbc7ad7dafd3c93ca2ad9e9534a6f5a237942",
12
+ "check/coda/application/host-protocols.mjs": "5ffe956f9ff5b38efac34a7d36a799f4249391b01a92b7c07b5f2c3c233b6f99",
13
+ "check/coda/components/protocols/protocol-events.mjs": "076f335287d0398c602ad6db286ab0001dc00ac42d32a23918a66ee37c3e9a2f",
12
14
  "check/coda/components/protocols/record-rules.mjs": "116bd103102afb94589d1df69786a780d2745165f46b878ddd48ac6d630694b1",
13
15
  "check/coda/components/protocols/types.mjs": "283cd0f4516f10637d6fe257fe645ead87912219d471c06408d56617f244e1d1",
14
16
  "check/coda/adapters/provider-api.mjs": "70441ea2a417ede13e04113ec254496883be3186f291ef5ee65834f35009eb9e",
15
17
  "check/coda/adapters/call-limit.mjs": "7e86d95ff7b0a88955015904ec91ae55e78fad816d06f710d6e62af53ccbdeab",
16
18
  "check/coda/adapters/clock.mjs": "79733b9ac3807b3da147fe8b782318a1cb42d1d51b9c8b81a507c13c7a8025fd",
17
- "check/coda/adapters/plugin-command.mjs": "526b4f57a549d9f74bac508f5803a592210cbf24ab67148260262f02d2bc75b5",
18
- "check/coda/adapters/plugin-modules.mjs": "5b02f9fd8eab68fb1564ab3640d137e383b59576e90a8d41f9a7feb804e13ff5",
19
+ "check/coda/adapters/plugin-command.mjs": "47bd580f7142780933315f64d4562d23a61f996b3f411cfb583333261b590ee8",
20
+ "check/coda/adapters/plugin-events.mjs": "8d63b55e333d3943d8c189d10439d5804372fbd831958491c93943f98cd078be",
21
+ "check/coda/adapters/plugin-modules.mjs": "a7b0dbface89d5b2b16885ab8b0bd87ff9b53ce31faee7c69d609ba7b53b83eb",
19
22
  "check/coda/adapters/plugin-stream-services.mjs": "1e92eb3dd9d844d4f2773a60bc2941aae3c9cda10d9e96e31de9f09f51e672e5",
20
- "check/coda/adapters/plugin-test-host.d.mts": "71d10d545761a2013b87f29815f42d779722e211484d70e0a732de31c5972c7d",
21
- "check/coda/adapters/plugin-test-host.mjs": "314ce4af2d0cdd1d3076f3e5af551ee3d3759ae01b6f670d2b84735e54fdfdac",
23
+ "check/coda/adapters/plugin-test-host.d.mts": "1a147a97f7e7391693a5a0acf79ce202d4d3afa8f3b580e6f379d0f10dfdf6ce",
24
+ "check/coda/adapters/plugin-test-host.mjs": "8c6e832eaeacaf95ac7d4a0e5594f907f609085155c830854ba3a390be085648",
22
25
  "check/coda/adapters/process-relay.mjs": "5d379bd7ad07138d69c7accbe769d71294843399539bdf1fab8b6a1ddf13b9d8",
23
26
  "check/coda/components/composers/contributions.mjs": "43d3e15fb1f63b7b5c20716030d9537613809ed5cc2fb466a3678bfa308f9f92",
24
27
  "check/coda/components/concurrency-groups/schemas.mjs": "3c422044c637dee10565fb1b8bdc75b9c6a31e3b600ed223b7e5e345e1baf092",
@@ -26,16 +29,17 @@
26
29
  "check/coda/components/plugins/contribution-points.mjs": "2dade9fe4f3fa2b4e89f49a1ac4378ab2621e5ac542eb175967091f04568b45c",
27
30
  "check/coda/components/plugins/git-contributions.mjs": "532917cd3ec45e12535e9e6c206ae14fa598bebc789ab0c8f15609d1699fa1cd",
28
31
  "check/coda/components/plugins/model-contributions.mjs": "018a7157954b2326887ba1a780b37d3beb33338e41a28936b313562c2939d563",
29
- "check/coda/components/plugins/plugin-extensions.mjs": "64089e6f0c58b60f922d93ac49cf5fa20d4541b39995e5170671d8a3d03f556f",
32
+ "check/coda/components/plugins/plugin-extensions.mjs": "ac1858346d94e41a2dcb030033d40df6c1f222b5de0759eb1f28d8db47c8097b",
30
33
  "check/coda/components/plugins/plugin-icons.mjs": "ec29cadce4948ecacabfe911a2ceb45414b96e28971358acbc4e952bedc78e1a",
31
- "check/coda/components/plugins/plugin-rules.mjs": "ee2d9fef03d5e82050114840444601b7f7d2e8b9645ea388cba0d6e3dede3432",
32
- "check/coda/components/plugins/plugin-source-rules.mjs": "099a2250cca737722c32524e40fc975c73abcfd4b99be7a9e5abcd5a68c211af",
34
+ "check/coda/components/plugins/plugin-rules.mjs": "32cf0a3956a646e0c18cea62da4c0969af9f4c6f60ab1a4970937163a13a878a",
35
+ "check/coda/components/plugins/plugin-source-rules.mjs": "d3bf278c4fb35e99f602ea81419dff0ad0c2753ee20e6e3b648d2fecf82da44f",
33
36
  "check/coda/components/plugins/process-contributions.mjs": "6d39a904f52956b87c04351398f79a4fc34981fa01453195bd7a3b9f2c5d237b",
34
37
  "check/coda/components/plugins/skill-document.mjs": "153ad3c096c7c9b7774bcf7dcc0ba603c962ee1ac8697c8a71e3f2c9ba9c92e6",
35
38
  "check/coda/components/prompt-recovery/prompt-recovery.mjs": "25477742af8a9134ae343af6ab702926692bdd8dd07844f3cba47e8b702c0e49",
36
39
  "check/coda/components/session-config/commands.mjs": "5276f81fc430a6eef7d7a0dbdecfffdb4a77f8c192cb0238ed73b7722641ce17",
37
40
  "check/coda/components/session-config/contributions.mjs": "74d52d65dc7b6f13ef301a211bdf50cc91ae468c462cbe201f5dc34f7437b97b",
38
- "check/coda/components/workflows/contributions.mjs": "e0cc743ed9bb382d00c0d65a99c8f8e601556b8396e7840cfc0bfb84ed2a4243",
41
+ "check/coda/components/workflows/contributions.mjs": "f16e36e5e591d7ab6c6e63f252e780717ba17bb4642aedd2797c5ff017df9d95",
42
+ "check/coda/components/workflows/workflow-protocol-definitions.mjs": "094ab1b2676f05fa88eb7ccd558b4eb4dce609fdf412f7663f84906ac2732186",
39
43
  "check/coda/domain/agent-protocol.mjs": "f1d7c939c240664b773c04d9a1c1e9457cc8396fd8f99f1d5b6b6964150843c0",
40
44
  "check/coda/domain/duration.mjs": "3f07411812362adcacfc288b1513f10e7d0ea1addcdc1b47ae553561f1d3430b",
41
45
  "check/coda/domain/errors.mjs": "15ad3348ea0e173a1a8602ec72766592cb41c0221420d9e5884bd68090ecc84b",
@@ -44,9 +48,12 @@
44
48
  "check/coda/domain/session-env.mjs": "283bbc2e8ae9ea22b53747865a651a4dac9c6cfc242f27612e0c82e6e9cc151a",
45
49
  "check/coda/domain/values.mjs": "afb8bf30e374bed27fe41ee4b6d8c3c0b4dbe1dcfb6b62dad9d3d53b966706a1",
46
50
  "check/coda/kernel/agent-failures.mjs": "cbc215e2403d86f0acc765c2077197e0b529fc01e213db465c388361238ea8ce",
51
+ "check/coda/kernel/plugin-protocol.mjs": "c514f9b6237404f8877dea568e4d425f1e380c19f3cb87764edf56f6c92ebd69",
52
+ "check/coda/kernel/project-protocol.mjs": "69874b2b226f111b156724454c968e829018f1caac0a02883f13e1f980482739",
53
+ "check/coda/kernel/thread-protocol.mjs": "58bbd66c0058552f26c1b4ed08231e9afd142f2b7a9f50ed6bd66cbfe8f579e1",
47
54
  "check/coda/resources/plugins/resources/panels/panels.mjs": "37ffc6a4ede3e4612cd13cf1a973a90892f8ce7e8a0f055e7cfe86313aae5224",
48
55
  "check/coda/resources/plugins/resources/panels/rules.mjs": "a433d4e84138937297ec31a8912aab7bd48bba4b66da3a10978edb1367613c96",
49
56
  "check/coda/resources/plugins/resources/panels/sign-in.mjs": "6eb016ef9a7f8aa03e0f4b2fa35ce139b8b1ff0deb4ec6e6a34139aed4f2841a",
50
- "check/coda/builtin.json": "6d8a803dc3503ea1fb68d526b2785fd73c7564d2ecd0cf24299055d0dda674dc"
57
+ "check/coda/builtin.json": "0eb63a693c912f7e339cda0b76b85110f881784b92c7788c8ea6d0a1c7468ade"
51
58
  }
52
59
  }
@@ -0,0 +1,56 @@
1
+ // Coda's own protocol of the plugins installed here, `coda/plugin@1`: what each is and how it stands on this machine, as a
2
+ // record. A record is an installed plugin, its ID the plugin's; it has no operation. Its records are read through from the
3
+ // `plugins` table (Protocols.serve) by what the plugins component says of them (components/plugins/plugins.mjs `installedView`):
4
+ // nothing is kept of them besides, and they are no section and not in the record directory.
5
+ import { createHash } from 'node:crypto';
6
+ import { canonical } from '../domain/values.mjs';
7
+
8
+ export const PLUGIN = 'coda/plugin@1';
9
+
10
+ const text = { type: 'string' };
11
+
12
+ export const PLUGIN_PROTOCOL = {
13
+ kind: PLUGIN,
14
+ title: '插件',
15
+ // Its name and version, and where it comes from: an npm package, a Git repository (at a branch and a commit), or Coda's own copy.
16
+ spec: {
17
+ type: 'object',
18
+ properties: {
19
+ name: text,
20
+ version: text,
21
+ source: {
22
+ type: 'object',
23
+ properties: { kind: { enum: ['builtin', 'npm', 'git'] }, package: text, version: text, repo: text, path: text, ref: text, commit: text },
24
+ required: ['kind'],
25
+ additionalProperties: false,
26
+ },
27
+ },
28
+ required: ['name', 'version', 'source'],
29
+ additionalProperties: false,
30
+ },
31
+ // How it is on this machine: ready, being taken (`fetching`), not running here (`incompatible`) or failed, and why (`error`).
32
+ status: {
33
+ type: 'object',
34
+ properties: { state: { enum: ['ready', 'fetching', 'incompatible', 'failed'] }, error: text },
35
+ required: ['state'],
36
+ additionalProperties: false,
37
+ },
38
+ operations: {},
39
+ // What a plugin may ask for in its `uses` (docs/plugins.md「用到的权限」), on trial while the protocol is not stable.
40
+ permissions: {
41
+ read: { title: '查看这台机器装了哪些插件', trial: true, read: true },
42
+ },
43
+ };
44
+
45
+ const SOURCE_KEYS = ['package', 'version', 'repo', 'path', 'ref', 'commit'];
46
+ // The record of one installed plugin, as `installedView` says it; its revision is what its spec and status say.
47
+ const record = ({ id, installedAt, sequence, name, version, source, local }) => {
48
+ const spec = { name, version, source: { kind: source.kind ?? 'builtin', ...Object.fromEntries(SOURCE_KEYS.filter(key => typeof source[key] === 'string').map(key => [key, source[key]])) } };
49
+ const status = { state: local.state, ...(local.error ? { error: local.error } : {}) };
50
+ return { kind: PLUGIN, id, provider: 'coda', instance: id, createdAt: new Date(installedAt).toISOString(), creationSequence: sequence, spec, status,
51
+ revision: `${id}:${createHash('sha256').update(canonical([spec, status])).digest('hex').slice(0, 16)}` };
52
+ };
53
+ export const pluginRecords = plugins => ({
54
+ get: id => { const view = plugins.installedView().find(each => each.id === id); return view ? record(view) : null; },
55
+ list: () => plugins.installedView().map(record),
56
+ });
@@ -0,0 +1,52 @@
1
+ // Coda's own protocol of the directories registered here, `coda/project@1`: a directory as a record, its ID the project's,
2
+ // what is asked of a directory and not of a session or a workflow in it (#2749 3.5) its queries — its branches. Its records
3
+ // are read through from the `projects` table (Protocols.serve), as `coda/thread@1`'s are from `threads`: one for each
4
+ // directory not deleted, by its name, never its path; nothing is kept of them besides, they are no section and not in the
5
+ // record directory (one of another machine is not read).
6
+ import { createHash } from 'node:crypto';
7
+ import { canonical } from '../domain/values.mjs';
8
+
9
+ export const PROJECT = 'coda/project@1';
10
+
11
+ export const PROJECT_PROTOCOL = {
12
+ kind: PROJECT,
13
+ title: '目录',
14
+ spec: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'], additionalProperties: false },
15
+ status: { type: 'object', additionalProperties: false },
16
+ operations: {
17
+ // Its branches, the default first and the rest by latest commit, as a new session reads them (for a `branch` input):
18
+ // `pending` while they are first read, `error` why they could not be.
19
+ branches: { safe: true, input: { type: 'object', additionalProperties: false }, result: {
20
+ type: 'object',
21
+ properties: { branches: { type: 'array', items: { type: 'string', minLength: 1 } }, default: { type: 'string' }, pending: { type: 'boolean' },
22
+ error: { type: 'string', minLength: 1 } },
23
+ required: ['branches', 'default'],
24
+ additionalProperties: false,
25
+ } },
26
+ },
27
+ // What a plugin may ask for in its `uses` (docs/plugins.md「用到的权限」), on trial while the protocol is not stable.
28
+ permissions: {
29
+ read: { title: '查看目录名与分支', trial: true, read: true, operations: ['branches'] },
30
+ },
31
+ };
32
+
33
+ const ROW = 'SELECT id, name, created_at, rowid AS sequence FROM projects WHERE deleted = 0';
34
+ const record = row => {
35
+ if (!row) return null;
36
+ const spec = { name: row.name }, status = {};
37
+ return { kind: PROJECT, id: row.id, provider: 'coda', createdAt: new Date(row.createdAt).toISOString(), creationSequence: row.sequence, spec, status,
38
+ revision: `${row.id}:${createHash('sha256').update(canonical([spec, status])).digest('hex').slice(0, 16)}` };
39
+ };
40
+ export const projectRecords = store => ({
41
+ get: id => record(store.one(`${ROW} AND id = ?`, id)),
42
+ list: () => store.all(`${ROW} ORDER BY created_at, rowid`).map(record),
43
+ });
44
+
45
+ // Its query through the unified call (components/protocols/calls.mjs `handle`): `branches`, read as the clients read them
46
+ // (`branches(projectId)`, SessionConfigService.branches, the same `GET /v1/projects/<id>/branches` answers with).
47
+ export function projectQueries(calls, { branches }) {
48
+ calls.handle(PROJECT, 'branches', async ({ held }) => {
49
+ const read = await branches(held.id);
50
+ return { branches: read.branches, default: read.defaultRef ?? '', ...(read.pending ? { pending: true } : {}), ...(read.error ? { error: String(read.error.message ?? read.error) } : {}) };
51
+ });
52
+ }