@camstack/develop 0.1.7 → 0.1.9

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,17 @@
1
+ import { type BrowseOptions, type MdnsResponse } from './mdns-browse.js';
2
+ export type AgentMdnsState = 'unpaired' | 'pending' | 'paired';
3
+ export interface MdnsAgent {
4
+ readonly nodeId: string;
5
+ /** Where the agent's API listens: the A record, else the packet's source. */
6
+ readonly host: string;
7
+ readonly port: number;
8
+ readonly version: string | null;
9
+ readonly state: AgentMdnsState;
10
+ /** Short leaf fingerprint, once paired. */
11
+ readonly fingerprint: string | null;
12
+ }
13
+ /** Fold the responses into agents. Pure, so it is tested without sockets. */
14
+ export declare function agentsFromResponses(responses: readonly MdnsResponse[]): readonly MdnsAgent[];
15
+ /** Listen for `_camstack-agent._tcp` for `timeoutMs`; never throws (no multicast = no agents). */
16
+ export declare function browseAgentsMdns(options: BrowseOptions): Promise<readonly MdnsAgent[]>;
17
+ //# sourceMappingURL=agent-browse.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-browse.d.ts","sourceRoot":"","sources":["../../src/hub-discovery/agent-browse.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,aAAa,EAElB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAA;AAEzB,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE9D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CACpC;AAeD,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,SAAS,EAAE,CA0B5F;AAED,kGAAkG;AAClG,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAyB5F"}
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Browse the LAN for agents over mDNS (D857): every agent publishes ONE
3
+ * `_camstack-agent._tcp` service for its API port, paired or not. The hub lists
4
+ * them so the operator picks an agent to pair instead of typing an address.
5
+ *
6
+ * The TXT record carries only public facts (node id, version, pairing state, and
7
+ * a leaf fingerprint once paired) — finding an agent grants nothing.
8
+ */
9
+ import { AGENT_MDNS_QUERY_NAME, AGENT_MDNS_TXT_KEYS } from '@camstack/types';
10
+ import { createRealMdnsSocket, } from './mdns-browse.js';
11
+ function parseTxt(entries) {
12
+ const out = new Map();
13
+ for (const entry of entries) {
14
+ const at = entry.indexOf('=');
15
+ if (at > 0)
16
+ out.set(entry.slice(0, at), entry.slice(at + 1));
17
+ }
18
+ return out;
19
+ }
20
+ function stateOf(value) {
21
+ return value === 'paired' || value === 'pending' ? value : 'unpaired';
22
+ }
23
+ /** Fold the responses into agents. Pure, so it is tested without sockets. */
24
+ export function agentsFromResponses(responses) {
25
+ const found = new Map();
26
+ for (const { records, from } of responses) {
27
+ for (const ptr of records) {
28
+ if (ptr.kind !== 'ptr' || ptr.name.toLowerCase() !== AGENT_MDNS_QUERY_NAME)
29
+ continue;
30
+ const srv = records.find((r) => r.kind === 'srv' && r.name === ptr.target);
31
+ if (srv?.kind !== 'srv')
32
+ continue;
33
+ const txtRecord = records.find((r) => r.kind === 'txt' && r.name === ptr.target);
34
+ const txt = txtRecord?.kind === 'txt' ? parseTxt(txtRecord.entries) : new Map();
35
+ const nodeId = txt.get(AGENT_MDNS_TXT_KEYS.nodeId);
36
+ // A service without a node id is not one of ours to list.
37
+ if (nodeId === undefined || nodeId.length === 0)
38
+ continue;
39
+ const a = records.find((r) => r.kind === 'a' && r.name === srv.target);
40
+ const host = a?.kind === 'a' ? a.address : from;
41
+ found.set(nodeId, {
42
+ nodeId,
43
+ host,
44
+ port: srv.port,
45
+ version: txt.get(AGENT_MDNS_TXT_KEYS.version) ?? null,
46
+ state: stateOf(txt.get(AGENT_MDNS_TXT_KEYS.state)),
47
+ fingerprint: txt.get(AGENT_MDNS_TXT_KEYS.keyFingerprint) ?? null,
48
+ });
49
+ }
50
+ }
51
+ return [...found.values()];
52
+ }
53
+ /** Listen for `_camstack-agent._tcp` for `timeoutMs`; never throws (no multicast = no agents). */
54
+ export async function browseAgentsMdns(options) {
55
+ const responses = [];
56
+ const problem = (error) => options.onProblem?.(error instanceof Error ? error.message : String(error));
57
+ let socket;
58
+ try {
59
+ socket = (options.createSocket ?? createRealMdnsSocket)();
60
+ }
61
+ catch (err) {
62
+ problem(err);
63
+ return [];
64
+ }
65
+ let requery = null;
66
+ try {
67
+ socket.onResponse((r) => responses.push(r));
68
+ socket.onError(problem);
69
+ socket.query(AGENT_MDNS_QUERY_NAME);
70
+ requery = setInterval(() => socket.query(AGENT_MDNS_QUERY_NAME), options.requeryMs ?? 1000);
71
+ await new Promise((resolve) => setTimeout(resolve, options.timeoutMs));
72
+ }
73
+ catch (err) {
74
+ problem(err);
75
+ }
76
+ finally {
77
+ if (requery !== null)
78
+ clearInterval(requery);
79
+ socket.destroy();
80
+ }
81
+ return agentsFromResponses(responses);
82
+ }
@@ -1,4 +1,5 @@
1
1
  /** Finding hubs on the LAN (D838) — shared by the CLI and the agent backend (D839). */
2
2
  export { type DiscoverHubsDeps, discoverHubs, type HubCandidate, mergeCandidates, MDNS_SOURCE_LABEL, normalizeHubUrl, probeHttps, type RawCandidate, } from './hub-candidates.js';
3
3
  export { type BrowseOptions, browseHubsMdns, createRealMdnsSocket, hubsFromResponses, type MdnsHub, type MdnsRecord, type MdnsResponse, type MdnsSocket, } from './mdns-browse.js';
4
+ export { type AgentMdnsState, agentsFromResponses, browseAgentsMdns, type MdnsAgent, } from './agent-browse.js';
4
5
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hub-discovery/index.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,EACL,KAAK,gBAAgB,EACrB,YAAY,EACZ,KAAK,YAAY,EACjB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,KAAK,YAAY,GAClB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,aAAa,EAClB,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hub-discovery/index.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,EACL,KAAK,gBAAgB,EACrB,YAAY,EACZ,KAAK,YAAY,EACjB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,KAAK,YAAY,GAClB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,aAAa,EAClB,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,KAAK,cAAc,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,SAAS,GACf,MAAM,mBAAmB,CAAA"}
@@ -1,3 +1,4 @@
1
1
  /** Finding hubs on the LAN (D838) — shared by the CLI and the agent backend (D839). */
2
2
  export { discoverHubs, mergeCandidates, MDNS_SOURCE_LABEL, normalizeHubUrl, probeHttps, } from './hub-candidates.js';
3
3
  export { browseHubsMdns, createRealMdnsSocket, hubsFromResponses, } from './mdns-browse.js';
4
+ export { agentsFromResponses, browseAgentsMdns, } from './agent-browse.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@camstack/develop",
3
- "version": "0.1.7",
3
+ "version": "0.1.9",
4
4
  "description": "CamStack developer tooling — catalogue, scaffold, validate, and example lookup shared by the CLI and MCP server.",
5
5
  "keywords": [
6
6
  "camstack",
@@ -39,9 +39,20 @@ lacks it. Tokens are never printed.
39
39
 
40
40
  ## 1. Triage — rank, do not judge
41
41
 
42
- `track_review_triage { hours, deviceIds?, classes? }` pages the window (default
43
- 72 h, at most 14 days), scores every video track, and returns the top suspects
44
- with their features, plus a **random control sample** of tracks that scored low.
42
+ `track_review_triage { hours, deviceIds?, classes?, excludeInTraining? }` pages the
43
+ window (default 72 h, at most 14 days), scores every video track, and returns the
44
+ top suspects with their features and `cameraName`, plus a **random control sample**
45
+ of tracks that scored low.
46
+
47
+ Each row carries `inTraining: { collections } | null`, read from the retrain corpus
48
+ in one bounded pass (never per track). Suspects already in the corpus are skipped
49
+ by default and counted in `skippedInTraining`; pass `excludeInTraining: false` to
50
+ see them anyway. If `trainingTruncated` is true the corpus was only partly read, so
51
+ `null` is not proof.
52
+
53
+ `few-observations` is **not evaluated by triage**: the slim rows it reads carry no
54
+ position history and fetching it would cost a call per track. The result says so in
55
+ `signalsNotEvaluated`; `track_review_frame` shows the observation count for one track.
45
56
 
46
57
  The score is a sum of cheap signals. None of them says "wrong"; together they say
47
58
  "look here first":
@@ -76,6 +87,12 @@ cap: narrow it.
76
87
  subject in the picture, not the label. If the frame is missing or too small to
77
88
  tell, the verdict is `unsure`.
78
89
 
90
+ A whole-scene frame (key frame, full frame) is preferred, and the envelope is in
91
+ that image's coordinates. If only the track's thumbnail CROP fits the size bound,
92
+ `imageSpace` is `crop`, a `WARNING` says so, and the envelope is withheld: it is in
93
+ full-frame coordinates and the crop's rectangle is unknown, so it would not line up.
94
+ Raise `maxBytes` to get the full frame.
95
+
79
96
  ## 3. Verdicts
80
97
 
81
98
  | Verdict | Meaning | Written? |
@@ -104,16 +121,17 @@ alongside the findings.
104
121
 
105
122
  ## 5. Plan, show, then apply
106
123
 
107
- 1. `track_review_plan { verdicts }` — local, writes nothing. It returns, per
108
- track, the steps (flag for training → copy the frame → save the corrected
124
+ 1. `track_review_plan { verdicts, collectionName? }` — local, writes nothing. It
125
+ keeps each verdict's `note`, carries `collectionName` so the plan is
126
+ self-contained, and returns, per track, the steps (flag for training → copy the frame → save the corrected
109
127
  boxes → mark complete → add to the collection), the subjects, and the
110
128
  verdicts that write nothing with their reason.
111
129
  2. **Present that write list to the operator and wait.** Name the tracks, the
112
130
  classes you will write, the collection, and how many frames will be marked
113
131
  complete. This is the only moment to catch a wrong call cheaply.
114
- 3. `track_review_apply { plan, collectionName, confirm: true }` — only after the
115
- operator agrees. It refuses without `confirm: true` and an explicit
116
- collection name.
132
+ 3. `track_review_apply { plan, collectionName?, confirm: true }` — only after the
133
+ operator agrees. It refuses without `confirm: true` and a collection name:
134
+ the argument if given, else `plan.collectionName` (the argument wins).
117
135
 
118
136
  Apply is safe to repeat: a frame already copied is reused, a frame that already
119
137
  has annotations is left alone (`overwrite: true` replaces them — a save replaces