@groundnuty/macf-core 0.2.54 → 0.2.55
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/dist/guest.d.ts +73 -0
- package/dist/guest.d.ts.map +1 -1
- package/dist/guest.js +50 -0
- package/dist/guest.js.map +1 -1
- package/package.json +1 -1
package/dist/guest.d.ts
CHANGED
|
@@ -23,6 +23,7 @@
|
|
|
23
23
|
*/
|
|
24
24
|
import { z } from 'zod';
|
|
25
25
|
import { MacfError } from './errors.js';
|
|
26
|
+
import type { AgentInfo } from './registry/types.js';
|
|
26
27
|
/**
|
|
27
28
|
* How the consumer reaches the guest (DR-036 §two enabler paths, Amendment A):
|
|
28
29
|
* - `route` — the guest is App-scoped + GitHub-@mention-routable
|
|
@@ -98,4 +99,76 @@ export declare function parseGuestAgentRef(agent: string): {
|
|
|
98
99
|
readonly homeProject: string;
|
|
99
100
|
readonly name: string;
|
|
100
101
|
};
|
|
102
|
+
/**
|
|
103
|
+
* DR-041 Amendment A (cross-fleet guest ADDRESSING, groundnuty/macf#786):
|
|
104
|
+
* resolve a guest's `<home-project>/<name>` registry slot to its `AgentInfo`.
|
|
105
|
+
* Mirrors `fleet-guests.ts`'s `GuestResolveFn` shape exactly — kept as an
|
|
106
|
+
* independent type here (rather than the reverse) so the outbound MESSAGING
|
|
107
|
+
* clients (`macf-channel-server`'s `notify_peer` + outbound A2A dispatch,
|
|
108
|
+
* `macf`'s `macf-ping` CLI) can depend on macf-core WITHOUT depending on the
|
|
109
|
+
* `macf` package's `fleet-guests.ts` (the STATUS-layer module, DR-036,
|
|
110
|
+
* which lives one package over and pulls in CLI-only concerns).
|
|
111
|
+
*/
|
|
112
|
+
export type CrossProjectAgentResolver = (homeProject: string, name: string) => Promise<AgentInfo | null>;
|
|
113
|
+
/**
|
|
114
|
+
* Outcome of resolving a `to` address string against DR-041 Amendment A's
|
|
115
|
+
* 4-rung cross-fleet guest resolution ladder (groundnuty/macf#786):
|
|
116
|
+
*
|
|
117
|
+
* 1. `to` parses as `<project>/<name>` + the home project is federated +
|
|
118
|
+
* the registry slot resolves → `resolved` — attempt delivery.
|
|
119
|
+
* 2. `to` parses but the home project is NOT in `federatedCas` →
|
|
120
|
+
* `not-federated` — clear DR-041 error, never a silent no-op.
|
|
121
|
+
* 3. `to` parses + home project federated, but the registry slot is
|
|
122
|
+
* missing/unresolvable → `not-found` — clear error.
|
|
123
|
+
* 4. `to` does NOT parse as a `<project>/<name>` slug at all →
|
|
124
|
+
* `not-a-guest-ref` — the caller falls through to its OWN, UNCHANGED
|
|
125
|
+
* own-project resolution. Deliberately NOT folded into this ladder:
|
|
126
|
+
* each call site's own-project lookup mechanics differ (a direct
|
|
127
|
+
* `registry.get(name)` in `notify-peer.ts` vs. a sanitized-name
|
|
128
|
+
* `list()`-then-`find()` in `macf-ping`), so unifying THAT part would
|
|
129
|
+
* require reshaping call sites that aren't broken, for no shared
|
|
130
|
+
* benefit — only the GUEST ladder (parse + trust-gate + cross-project
|
|
131
|
+
* resolve + error text) is common enough to be worth one shared
|
|
132
|
+
* implementation.
|
|
133
|
+
*/
|
|
134
|
+
export type GuestAddressResolution = {
|
|
135
|
+
readonly kind: 'not-a-guest-ref';
|
|
136
|
+
} | {
|
|
137
|
+
readonly kind: 'not-federated';
|
|
138
|
+
readonly homeProject: string;
|
|
139
|
+
readonly name: string;
|
|
140
|
+
readonly error: string;
|
|
141
|
+
} | {
|
|
142
|
+
readonly kind: 'not-found';
|
|
143
|
+
readonly homeProject: string;
|
|
144
|
+
readonly name: string;
|
|
145
|
+
readonly error: string;
|
|
146
|
+
} | {
|
|
147
|
+
readonly kind: 'resolved';
|
|
148
|
+
readonly homeProject: string;
|
|
149
|
+
readonly name: string;
|
|
150
|
+
readonly info: AgentInfo;
|
|
151
|
+
};
|
|
152
|
+
/**
|
|
153
|
+
* DR-041 Amendment A's unified cross-fleet guest resolution ladder
|
|
154
|
+
* (groundnuty/macf#786) — the SINGLE implementation `notify_peer` (outbound
|
|
155
|
+
* `/notify` + outbound A2A `message/send`, both dispatch through the SAME
|
|
156
|
+
* resolved peer in `notify-peer.ts`) and `macf-ping` reuse, so the addressing
|
|
157
|
+
* gate + its exact error text can never drift between call sites.
|
|
158
|
+
*
|
|
159
|
+
* Gated on `federatedCas` ALONE (DR-041 Amendment A decision 1) — NEVER on a
|
|
160
|
+
* `guests` binding. Rationale (science-ratified on macf#786): trust (the
|
|
161
|
+
* per-fleet-CA mTLS bundle, #785) is the SOLE admission gate for cross-fleet
|
|
162
|
+
* addressing — once a fleet's CA is federated, every agent that CA has
|
|
163
|
+
* signed is mTLS-reachable, so gating addressing on that SAME set keeps
|
|
164
|
+
* "can I address it" and "can I mTLS it" consistent. The `guests` binding
|
|
165
|
+
* (`.github/macf-fleet.json` `guests[]`) remains a relationship/metadata
|
|
166
|
+
* layer (DR-036) — consulted for scope-awareness in a FUTURE amendment
|
|
167
|
+
* (`scope_out`/`capabilities`, #779), never a second hard addressing gate.
|
|
168
|
+
*
|
|
169
|
+
* A malformed / non-slug `to` (rung 4) is NOT an error here — it returns
|
|
170
|
+
* `{ kind: 'not-a-guest-ref' }` so the caller falls through to its own
|
|
171
|
+
* unchanged own-project resolution, byte-identical to pre-#786 behavior.
|
|
172
|
+
*/
|
|
173
|
+
export declare function resolveGuestAddress(to: string, federatedCas: readonly string[], resolve: CrossProjectAgentResolver): Promise<GuestAddressResolution>;
|
|
101
174
|
//# sourceMappingURL=guest.d.ts.map
|
package/dist/guest.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"guest.d.ts","sourceRoot":"","sources":["../src/guest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"guest.d.ts","sourceRoot":"","sources":["../src/guest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,sCAAuC,CAAC;AACvE,eAAO,MAAM,sBAAsB;;;EAA6B,CAAC;AACjE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAUtE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;iBAgB7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;iBAuBhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,yEAAyE;AACzE,qBAAa,gBAAiB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,CASlE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAQA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GAAG,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpC;IACE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,sBAAsB,CAAC,CA+BjC"}
|
package/dist/guest.js
CHANGED
|
@@ -131,4 +131,54 @@ export function parseGuestAgentRef(agent) {
|
|
|
131
131
|
}
|
|
132
132
|
return { homeProject: agent.slice(0, slash), name: agent.slice(slash + 1) };
|
|
133
133
|
}
|
|
134
|
+
/**
|
|
135
|
+
* DR-041 Amendment A's unified cross-fleet guest resolution ladder
|
|
136
|
+
* (groundnuty/macf#786) — the SINGLE implementation `notify_peer` (outbound
|
|
137
|
+
* `/notify` + outbound A2A `message/send`, both dispatch through the SAME
|
|
138
|
+
* resolved peer in `notify-peer.ts`) and `macf-ping` reuse, so the addressing
|
|
139
|
+
* gate + its exact error text can never drift between call sites.
|
|
140
|
+
*
|
|
141
|
+
* Gated on `federatedCas` ALONE (DR-041 Amendment A decision 1) — NEVER on a
|
|
142
|
+
* `guests` binding. Rationale (science-ratified on macf#786): trust (the
|
|
143
|
+
* per-fleet-CA mTLS bundle, #785) is the SOLE admission gate for cross-fleet
|
|
144
|
+
* addressing — once a fleet's CA is federated, every agent that CA has
|
|
145
|
+
* signed is mTLS-reachable, so gating addressing on that SAME set keeps
|
|
146
|
+
* "can I address it" and "can I mTLS it" consistent. The `guests` binding
|
|
147
|
+
* (`.github/macf-fleet.json` `guests[]`) remains a relationship/metadata
|
|
148
|
+
* layer (DR-036) — consulted for scope-awareness in a FUTURE amendment
|
|
149
|
+
* (`scope_out`/`capabilities`, #779), never a second hard addressing gate.
|
|
150
|
+
*
|
|
151
|
+
* A malformed / non-slug `to` (rung 4) is NOT an error here — it returns
|
|
152
|
+
* `{ kind: 'not-a-guest-ref' }` so the caller falls through to its own
|
|
153
|
+
* unchanged own-project resolution, byte-identical to pre-#786 behavior.
|
|
154
|
+
*/
|
|
155
|
+
export async function resolveGuestAddress(to, federatedCas, resolve) {
|
|
156
|
+
let ref;
|
|
157
|
+
try {
|
|
158
|
+
ref = parseGuestAgentRef(to);
|
|
159
|
+
}
|
|
160
|
+
catch {
|
|
161
|
+
return { kind: 'not-a-guest-ref' };
|
|
162
|
+
}
|
|
163
|
+
const { homeProject, name } = ref;
|
|
164
|
+
if (!federatedCas.includes(homeProject)) {
|
|
165
|
+
return {
|
|
166
|
+
kind: 'not-federated',
|
|
167
|
+
homeProject,
|
|
168
|
+
name,
|
|
169
|
+
error: `guest ${homeProject}/${name}: home fleet '${homeProject}' not in federated_cas — ` +
|
|
170
|
+
'federate it (DR-041) to message this guest.',
|
|
171
|
+
};
|
|
172
|
+
}
|
|
173
|
+
const info = await resolve(homeProject, name);
|
|
174
|
+
if (info === null) {
|
|
175
|
+
return {
|
|
176
|
+
kind: 'not-found',
|
|
177
|
+
homeProject,
|
|
178
|
+
name,
|
|
179
|
+
error: `guest ${homeProject}/${name} not found in registry.`,
|
|
180
|
+
};
|
|
181
|
+
}
|
|
182
|
+
return { kind: 'resolved', homeProject, name, info };
|
|
183
|
+
}
|
|
134
184
|
//# sourceMappingURL=guest.js.map
|
package/dist/guest.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"guest.js","sourceRoot":"","sources":["../src/guest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"guest.js","sourceRoot":"","sources":["../src/guest.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@groundnuty/macf-core",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.55",
|
|
4
4
|
"description": "Shared internals consumed by the MACF CLI and channel-server packages. Not intended for direct external use — will be marked deprecated-internal on first npm publish per DR-022 Amendment A.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|