@10xagents/connector-multica 0.0.1 → 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/README.md CHANGED
@@ -1,3 +1,120 @@
1
1
  # @10xagents/connector-multica
2
2
 
3
- Reserved. The first release is coming soon.
3
+ The Multica connector lets `10xagents` keep a [Multica](https://multica.ai) workspace in line with your setup: its agents, skills, squad, Default workflow and Agent context. It also measures how the team does there, from Multica's own records of requests, runs and reviews. It changes only what differs, and leaves what only a person can do, like creating an agent, to you.
4
+
5
+ ## Install
6
+
7
+ Install it beside the CLI, since `10xagents` loads the connector a target names as `connector: multica` from this package:
8
+
9
+ ```bash
10
+ npm install --save-dev 10xagents @10xagents/connector-multica
11
+ ```
12
+
13
+ The connector works through the `multica` CLI, logged in to the workspace you sync. It looks for it in this order:
14
+
15
+ 1. `$MULTICA`.
16
+ 2. `$MULTICA_CLI_PATH`.
17
+ 3. `multica` on `PATH`.
18
+ 4. The macOS Desktop app's copy, in `/Applications/Multica.app/Contents/Resources/app.asar.unpacked/resources/bin/multica`.
19
+
20
+ ## Usage
21
+
22
+ Point a target at the workspace, by its slug, name or id, and set `vars.owner` to the member who takes the owner's steps:
23
+
24
+ ```yaml
25
+ id: my-team
26
+ workspace: my-workspace
27
+ connector: multica
28
+ workflows: [request]
29
+ agents: [lead, builder, reviewer]
30
+ vars:
31
+ owner: Sam Lee
32
+ squad:
33
+ name: Starter
34
+ leader: lead
35
+ ```
36
+
37
+ Then compare and sync:
38
+
39
+ ```bash
40
+ npx 10xagents plan --profile my-profile --diff
41
+ npx 10xagents sync --profile my-profile
42
+ ```
43
+
44
+ Each command uses one Multica CLI profile: the one `--profile` names, the only one that's logged in, or the one you pick from a list. Without a terminal to ask in and with several profiles logged in, pass `--profile`. The connector runs `multica` from your home folder, without any `MULTICA_*` variables of its own environment, since the CLI prefers them to the profile's token and server. That way an agent run that syncs uses the profile you named, not the run's own account.
45
+
46
+ ## Capabilities
47
+
48
+ | Capability | Value | Why |
49
+ | ------------------ | ----- | ------------------------------------------------------------------------------------------------------ |
50
+ | `sharedContext` | yes | The global traits go into the workspace's Agent context, which Multica writes into every agent's brief |
51
+ | `workflowPerIssue` | no | Multica attaches workflows to projects, so an issue can't pick its own |
52
+ | `squads` | yes | The target's squad becomes a Multica squad, with its leader and each member's role |
53
+ | `skills` | yes | The setup's and the target's skills are imported into the workspace and attached to agents |
54
+ | `metrics` | 48 | Every metric in the Outcome, Review and Cost and time groups of the catalogue |
55
+
56
+ ## What it syncs
57
+
58
+ `plan` compares each of these with the workspace, and `sync` applies what differs, in this order:
59
+
60
+ | Item | How it's matched | What changes |
61
+ | ------------- | ---------------------------- | -------------------------------------------------------------------------------------------- |
62
+ | Skills | By name | A skill that's missing, or whose files differ, is imported whole, replacing the live one |
63
+ | Agents | By `name` | Instructions, description, model, thinking level and concurrency. Skills are only ever added |
64
+ | Squad | By the target's `squad.name` | Its instructions, members, their roles and its leader |
65
+ | Workflow | The workspace's Default | Every column, with its name, handoff, step text and moves |
66
+ | Agent context | The workspace's own | The global traits |
67
+
68
+ A few things it leaves to you, and says so with a `!` line:
69
+
70
+ - **Agents and squads.** It never creates one, so create each agent and the squad with the names the setup gives, then run `sync` again.
71
+ - **Disabled skills.** A run loads only enabled skills, so a skill that's attached but switched off has to be switched on in the agent's Skills tab.
72
+ - **The owner.** `handoff: owner` goes to the workspace member whose full name is `vars.owner`, or whose first name is, when only one member matches. A name that matches nobody, or several people, stops the workflow's sync until you fix it.
73
+
74
+ It also never removes a skill from an agent, since one you attached by hand stays, and never moves a project to another workflow: a project on another one shows as a `·` line with the command that switches it back. The Agent context describes the workflow, so while the workflow can't sync, the context waits too.
75
+
76
+ Skills are checked before anything is read. Each one needs a `SKILL.md` whose `name` matches its folder, and none can hold a file Multica's import leaves out, like a dotfile, a licence or a binary, since that file would show as a change on every run.
77
+
78
+ ## Workflows on Multica
79
+
80
+ Multica gives each workspace one Default workflow, so the connector merges a target's workflows into it, in the order the target lists them:
81
+
82
+ - **Built-in columns are shared.** Backlog, Todo, In Progress, In Review, Blocked, Done and Cancelled keep Multica's names, and every workflow that has one uses the same column. Two workflows have to agree on its handoff, step and moves.
83
+ - **The first workflow keeps its column names.** A custom column takes its `name`, or its key in title case, so `plan_review` becomes Plan Review.
84
+ - **Every later workflow's columns are prefixed** with the workflow's `prefix`, or with its id in title case when it has none, so `part`'s `planning` becomes Part Planning, and with `prefix: In Parts /`, In Parts / Planning. The first workflow ignores its `prefix`, so the same workflow can come first in one target and later in another.
85
+
86
+ Multica makes a custom status's key from its first name and keeps it when you rename the status, so with no `prefix`, Part Planning gets the key `part_planning`, and a workflow with a `prefix` gets keys made from its prefixed names. A workspace whose statuses were renamed keeps their old keys, and `multica issue-status list` shows each status's key. `{{workflows.<id>.columns.<key>}}` renders the names, so the texts name the columns as the workspace shows them.
87
+
88
+ To rename a live workspace's columns, for example when you add a `prefix`, rename each status first, then run `sync`:
89
+
90
+ ```bash
91
+ multica issue-status update part_planning --name "In Parts / Planning"
92
+ ```
93
+
94
+ `sync` never renames a status. It matches the workspace's custom statuses to the columns by their place, but when it writes the workflow, it finds each custom column's status by its name. So without the rename, a sync where nothing else differs keeps the old names, and one that changes the workflow, like a step whose text names the column, creates a status with the new name and drops the old one from the workflow. Multica doesn't move issues, so those on the old status stay on it, under a hidden column.
95
+
96
+ `build`, `plan` and `sync` stop on what Multica would refuse or put back another way:
97
+
98
+ - A workflow lists `backlog` and `todo` first, and `blocked`, `done` and `cancelled` last.
99
+ - Backlog, Done and Cancelled hand nothing off, so their `handoff` is `none`.
100
+ - Some workflow has a `todo`, a `done` and a `cancelled` column.
101
+ - A step's text is at most 8000 characters, and an agent's description at most 255.
102
+ - No custom column takes a built-in status's name, or another column's.
103
+
104
+ ## Benchmarking
105
+
106
+ `10xagents bench` reads the workspace's agents and issues, and each issue's runs, timeline and comments, and writes nothing. A request is an issue a person created with no parent, together with its sub-issues. The connector reports the Outcome, Review and Cost and time metrics of the catalogue, and the Claude Code collector in `10xagents` reports the Context ones.
107
+
108
+ The review metrics need to know which statuses are review steps. The defaults are `quality_assurance` and `plan_review`, so a setup with a second workflow's review columns, like a `part` workflow's, passes them too:
109
+
110
+ ```bash
111
+ npx 10xagents bench --review-step quality_assurance --review-step part_quality_assurance --plan-step plan_review --plan-step part_plan_review
112
+ ```
113
+
114
+ The verdict metrics, like `first-verdicts` and `fix-answers`, read `VERDICT:` comments with a findings ledger, which an older squad protocol wrote. In a window without them, they're `n/a`.
115
+
116
+ A `multica` CLI from before 20 August 2026 has no `issue timeline`, so the connector then reads each timeline from the server, with the address and token in the profile's config. The token travels in a header, never on a command line.
117
+
118
+ ## Library
119
+
120
+ The package exports the connector as `connector` and as its default export, and `createConnector(options)` for one that reads another environment. It also exports the helpers `10xagents` doesn't need, like `columnNames`, `mergeWorkflows`, `findMultica`, `listProfiles` and `MULTICA_METRICS`.
@@ -0,0 +1,339 @@
1
+ import { BenchQuery, BenchResult, ColumnNames, Connector, ConnectorIssue, RenderedSetup, Workflow } from "10xagents";
2
+ /** Where the macOS Desktop app keeps its copy of the CLI. */
3
+ export declare const DESKTOP_CLI = "/Applications/Multica.app/Contents/Resources/app.asar.unpacked/resources/bin/multica";
4
+ type Env = Readonly<Record<string, string | undefined>>;
5
+ /**
6
+ * The CLI to run: `$MULTICA`, then `$MULTICA_CLI_PATH`, then `multica` on `PATH`, then the macOS
7
+ * Desktop app's. Throws when there's none.
8
+ */
9
+ export declare const findMultica: (env: Env, desktop?: string) => string;
10
+ /**
11
+ * The environment `multica` runs in. Every inherited `MULTICA_*` variable goes, since the CLI
12
+ * prefers them to the profile's own token, server and workspace: an agent run's would otherwise
13
+ * sync another account. Only the workspace this call is for comes back.
14
+ */
15
+ export declare const childEnv: (env: Env, workspace?: string) => Record<string, string>;
16
+ interface MulticaCli {
17
+ bin: string;
18
+ /** `--profile <name>`, or nothing for the default profile. */
19
+ profileArgs: string[];
20
+ env: Env;
21
+ }
22
+ /** Multica's built-in statuses, by key, with their names. */
23
+ export declare const BUILT_IN: Readonly<Record<string, string>>;
24
+ /** The most characters Multica takes in a step's instructions. */
25
+ export declare const MAX_STEP = 8000;
26
+ /** The most characters Multica takes in an agent's description. */
27
+ export declare const MAX_DESCRIPTION = 255;
28
+ /**
29
+ * The Multica name of each column: a built-in column's own, the first workflow's custom columns
30
+ * by their `name` (or their key, in title case), and every later workflow's prefixed with the
31
+ * workflow's `prefix`, or its id in title case. The first workflow's `prefix` is ignored, so a
32
+ * workflow can come first in one target and later in another.
33
+ */
34
+ export declare const columnNames: (workflows: readonly Workflow[]) => ColumnNames;
35
+ /** One column of the merged workflow. */
36
+ interface MergedColumn {
37
+ /** Its Multica name. */
38
+ name: string;
39
+ /** Its key, for a built-in column. Multica gives a custom column's key. */
40
+ key?: string;
41
+ /** Its category, for a custom column. */
42
+ category?: string;
43
+ /** `agent:<id>`, `owner` or `none`. */
44
+ handoff: string;
45
+ instructions?: string;
46
+ /** Where `next` and `back` move to, as places in the merged list. */
47
+ next?: number;
48
+ back?: number;
49
+ /** The workflow and key of each column it came from: two for a shared built-in column. */
50
+ from: {
51
+ workflow: string;
52
+ key: string;
53
+ }[];
54
+ }
55
+ interface Merged {
56
+ columns: MergedColumn[];
57
+ issues: ConnectorIssue[];
58
+ }
59
+ /** Merges `rendered`'s workflows, in Multica's order, and reports what can't merge. */
60
+ export declare const mergeWorkflows: (rendered: RenderedSetup) => Merged;
61
+ /**
62
+ * The profiles that hold a token, by name: `""` is the default profile. `multica auth logout`
63
+ * leaves a config without a token, and an unreadable config logs nobody in.
64
+ */
65
+ export declare const listProfiles: (home: string) => string[];
66
+ interface Issue {
67
+ id: string;
68
+ identifier?: string;
69
+ title?: string;
70
+ parent_issue_id?: string | null;
71
+ creator_type?: string;
72
+ status?: string;
73
+ created_at: string;
74
+ updated_at?: string;
75
+ last_activity_at?: string;
76
+ metadata?: {
77
+ pr_url?: string;
78
+ } | null;
79
+ }
80
+ interface Usage {
81
+ model?: string;
82
+ input_tokens?: number;
83
+ output_tokens?: number;
84
+ cache_read_tokens?: number;
85
+ cache_write_tokens?: number;
86
+ }
87
+ interface Run {
88
+ id: string;
89
+ agent_id: string;
90
+ status: string;
91
+ attempt?: number;
92
+ trigger_summary?: string | null;
93
+ created_at?: string;
94
+ started_at?: string | null;
95
+ completed_at?: string | null;
96
+ failure_reason?: string | null;
97
+ is_leader_task?: boolean;
98
+ priority?: string | number | null;
99
+ usage?: Usage[] | null;
100
+ }
101
+ interface TimelineEntry {
102
+ type?: string;
103
+ action?: string;
104
+ created_at?: string;
105
+ actor_type?: string;
106
+ details?: {
107
+ from?: string;
108
+ to?: string;
109
+ } | null;
110
+ content?: string;
111
+ }
112
+ interface Attachment {
113
+ id: string;
114
+ filename?: string;
115
+ }
116
+ interface Comment {
117
+ author_id?: string;
118
+ author_type?: string;
119
+ created_at: string;
120
+ content?: string;
121
+ attachments?: Attachment[] | null;
122
+ }
123
+ /** A timeline, and whether the server cut it short. */
124
+ interface Timeline {
125
+ data: TimelineEntry[];
126
+ warnings: string;
127
+ }
128
+ /** What the measures read, so tests can hand them fixtures. */
129
+ interface BenchSource {
130
+ workspace: {
131
+ id: string;
132
+ name: string;
133
+ slug: string;
134
+ };
135
+ /** Agent names by id, archived agents included. */
136
+ agentNames: Map<string, string>;
137
+ /** Every issue in the workspace, oldest first. */
138
+ issues: Issue[];
139
+ runs(issueId: string): Run[];
140
+ timeline(issueId: string, statusOnly: boolean): Promise<Timeline>;
141
+ comments(issueId: string): Comment[];
142
+ /** An attachment's text, or `null` when it can't be read. */
143
+ attachment(attachment: Attachment): string | null;
144
+ /** Lines worth showing, like a timeline read from the server. */
145
+ notes: string[];
146
+ /** Removes what it downloaded. */
147
+ close(): void;
148
+ }
149
+ /** One request's numbers. Identifiers, dates, counts and costs only. */
150
+ interface RequestRow {
151
+ request: string;
152
+ segment: string;
153
+ created: string;
154
+ firstRun: string;
155
+ outcome: "done" | "stopped" | "open";
156
+ leadHours: number;
157
+ issues: number;
158
+ linkedIssues: string[];
159
+ runs: number;
160
+ failedRuns: number;
161
+ agentHours: number;
162
+ cost: number | null;
163
+ costKnown: number;
164
+ reviewRounds: number;
165
+ planReviews: number;
166
+ peopleActions: number;
167
+ waitedHours: number;
168
+ }
169
+ /** One run's timings, kind, status, failure reason and tokens. No comment text. */
170
+ interface RunRow {
171
+ run: string;
172
+ segment: string | null;
173
+ issue: string;
174
+ issueId: string;
175
+ parent: string | null;
176
+ agent: string;
177
+ leader: boolean;
178
+ priority: string | number | null;
179
+ status: string;
180
+ failureReason: string | null;
181
+ kind: string;
182
+ attempt: number | undefined;
183
+ created: string | undefined;
184
+ started: string | null | undefined;
185
+ completed: string | null | undefined;
186
+ queueMin: number;
187
+ runMin: number;
188
+ usage: {
189
+ input: number;
190
+ output: number;
191
+ cacheRead: number;
192
+ cacheWrite: number;
193
+ };
194
+ models: string[];
195
+ cost: number | null;
196
+ }
197
+ /** One review cycle on a work issue, from a delivery to its verdict. */
198
+ interface CycleRow {
199
+ issue: string;
200
+ segment: string;
201
+ kind: string;
202
+ wakeups: number;
203
+ total: number;
204
+ queue: number;
205
+ work: number;
206
+ ciGap: number;
207
+ cost: number | null;
208
+ }
209
+ interface Finding {
210
+ id: string;
211
+ origin: string | null;
212
+ state: string | null;
213
+ raisedRound: number | null;
214
+ }
215
+ interface VerdictEvent {
216
+ type: "verdict";
217
+ at: string;
218
+ author: string;
219
+ result: string;
220
+ round: number | null;
221
+ report: string | null;
222
+ blocking: Finding[];
223
+ settled: Finding[];
224
+ nits: number;
225
+ needsDecision: number;
226
+ }
227
+ interface HandoffEvent {
228
+ type: string;
229
+ variant: string | null;
230
+ at: string;
231
+ author: string;
232
+ answers: {
233
+ id: string;
234
+ answer: string;
235
+ }[];
236
+ }
237
+ /** One work issue with a verdict in the window, and what happened on it up to `--until`. */
238
+ interface VerdictRow {
239
+ issue: string;
240
+ parent: string | null;
241
+ repository: string | null;
242
+ segment: string | null;
243
+ events: (VerdictEvent | HandoffEvent)[];
244
+ }
245
+ /** Every metric the Multica connector reports. */
246
+ export declare const MULTICA_METRICS: string[];
247
+ /** Measures everything from `source`. Tests hand it a source of fixtures. */
248
+ export declare const benchFrom: (source: BenchSource, query: BenchQuery) => Promise<BenchResult>;
249
+ interface LiveWorkspace {
250
+ id: string;
251
+ name: string;
252
+ slug: string;
253
+ }
254
+ interface LiveMember {
255
+ user_id: string;
256
+ name: string;
257
+ email?: string;
258
+ }
259
+ interface LiveSkill {
260
+ id: string;
261
+ name: string;
262
+ /** Every file, by path, as stored. `SKILL.md` is the skill's content. */
263
+ files: Record<string, string>;
264
+ }
265
+ interface LiveAgent {
266
+ id: string;
267
+ name: string;
268
+ description: string;
269
+ model: string;
270
+ thinking_level: string;
271
+ max_concurrent_tasks: string;
272
+ instructions: string;
273
+ skills: {
274
+ name: string;
275
+ enabled: boolean;
276
+ }[];
277
+ }
278
+ interface LiveSquad {
279
+ id: string;
280
+ name: string;
281
+ instructions: string;
282
+ leader_id: string;
283
+ members: {
284
+ member_id: string;
285
+ member_type: string;
286
+ role: string;
287
+ }[];
288
+ }
289
+ interface LiveStep {
290
+ status_key: string;
291
+ handler?: {
292
+ type: string;
293
+ id?: string;
294
+ };
295
+ instructions?: string;
296
+ next_status_key?: string;
297
+ back_status_key?: string;
298
+ }
299
+ /** The Default workflow, or why it can't be synced. */
300
+ type LiveWorkflow = {
301
+ problem: string;
302
+ } | {
303
+ id: string;
304
+ steps: LiveStep[];
305
+ project_ids: string[];
306
+ };
307
+ /** The Multica connector's live state. */
308
+ type MulticaLive = {
309
+ connector: "multica";
310
+ cli: MulticaCli;
311
+ /** The profile's name, `""` for the default one. */
312
+ profile: string;
313
+ workspace: LiveWorkspace;
314
+ context: string;
315
+ members: LiveMember[];
316
+ skills: LiveSkill[];
317
+ agents: LiveAgent[];
318
+ /** The target's squad, `null` when the workspace has none with its name. */
319
+ squad: LiveSquad | null;
320
+ workflow: LiveWorkflow;
321
+ projects: {
322
+ id: string;
323
+ name: string;
324
+ }[];
325
+ };
326
+ /** The platform this connector syncs to. */
327
+ export declare const platform = "multica";
328
+ export interface MulticaConnectorOptions {
329
+ /** The environment to read `MULTICA`, `PATH` and `HOME` from. The default is `process.env`. */
330
+ env?: Env;
331
+ /** Where the macOS Desktop app keeps its CLI. */
332
+ desktop?: string;
333
+ }
334
+ /** What Multica would refuse in `rendered`, checked before anything is read. */
335
+ export declare const validate: (rendered: RenderedSetup) => ConnectorIssue[];
336
+ /** A Multica connector that reads its environment from `options`. */
337
+ export declare const createConnector: (options?: MulticaConnectorOptions) => Connector;
338
+ export declare const connector: Connector;
339
+ export { type BenchSource, type CycleRow, type MulticaLive, type RequestRow, type RunRow, type VerdictRow, connector as default };