@mmon-co/ncept-bb 0.0.0-stage → 0.1.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.
@@ -0,0 +1,11 @@
1
+ {
2
+ "sdkMajor": 0,
3
+ "sdkVersion": "0.6.132",
4
+ "artifactFormatVersion": 1,
5
+ "pluginId": "ncept-bb",
6
+ "pluginVersion": "0.1.0",
7
+ "builtWith": {
8
+ "bbVersion": "0.49.0",
9
+ "pluginSdkVersion": "0.6.132"
10
+ }
11
+ }
package/package.json CHANGED
@@ -1,6 +1,71 @@
1
1
  {
2
2
  "name": "@mmon-co/ncept-bb",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "One bb thread per Common Concept tutoring Session",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/mmon-co/ncept.git",
9
+ "directory": "packages/bb"
10
+ },
11
+ "files": [
12
+ "dist",
13
+ "src",
14
+ "skills",
15
+ "README.md",
16
+ "LICENSE"
17
+ ],
18
+ "type": "module",
19
+ "scripts": {
20
+ "build": "bun run --cwd ../pi build && bb plugin build",
21
+ "source:install": "bun scripts/source-install.ts",
22
+ "encounter:entries": "bun scripts/entry-encounter.ts",
23
+ "prepack": "bun run build"
24
+ },
25
+ "dependencies": {
26
+ "@dagrejs/dagre": "3.1.3",
27
+ "@mmon-co/ncept-core": "^0.2.0",
28
+ "@mmon-co/ncept-default-theory": "^1.1.0",
29
+ "@mmon-co/ncept-local": "^0.2.0",
30
+ "@mmon-co/ncept-pi": "^0.2.0",
31
+ "@xyflow/react": "12.10.1",
32
+ "d3-force": "3.0.0",
33
+ "zod": "^4.6.5"
34
+ },
35
+ "devDependencies": {
36
+ "@earendil-works/pi-ai": "1.5.0",
37
+ "@earendil-works/pi-coding-agent": "1.5.0",
38
+ "@get-bb/plugin-sdk": "0.6.104",
39
+ "@types/d3-force": "3.0.10",
40
+ "@types/react": "19.2.18",
41
+ "bun-types": "^1.3.14",
42
+ "react": "19.2.8",
43
+ "typescript": "5.9.3"
44
+ },
45
+ "peerDependencies": {
46
+ "@earendil-works/pi-coding-agent": "*"
47
+ },
48
+ "engines": {
49
+ "bb": ">=0.48.1",
50
+ "bbPluginSdk": ">=0.6.104",
51
+ "node": ">=22.19.0"
52
+ },
53
+ "bb": {
54
+ "name": "Common Concept",
55
+ "description": "Learn from a Profile you own, with a thread per tutoring Session.",
56
+ "branding": {
57
+ "icon": "BookOpen"
58
+ },
59
+ "server": "./src/server.ts",
60
+ "app": "./src/app.tsx",
61
+ "host": "./src/host.ts",
62
+ "skills": [
63
+ "skills"
64
+ ]
65
+ },
66
+ "pi": {
67
+ "extensions": [
68
+ "./src/extension.ts"
69
+ ]
70
+ }
71
+ }
@@ -0,0 +1,12 @@
1
+ ---
2
+ name: ncept-bb
3
+ description: "Create a Common Concept learning Profile and bb project."
4
+ ---
5
+
6
+ Use `bb concept init [dir]` (default ~/learn). `--machine <id-or-name>` selects its machine; without it, the current thread's machine or the server is used. Initialization saves pi's trust entry on that machine.
7
+
8
+ Start the project's first thread with pi. ncept-pi owns tutoring and Profile writes; the bb extension opens each next Session in a sibling thread and each aside in a child. The outgoing conversation links to it.
9
+
10
+ For unpublished source on the bb server, run `bun packages/bb/scripts/source-install.ts <server-machine-id>` to build and install the durable main checkout, then pass its absolute packages/bb path as `--source` to init. This also selects sibling packages/pi. See the package README for first use.
11
+
12
+ `spawn --request-file <absolute-path>`, `associate --session <id>` and `carry --thread <id>` are transport commands used by the extension. Learn controls use the typed `open` and `thread` RPC in `src/contract.ts`; the package README describes their entries.
package/src/app.tsx ADDED
@@ -0,0 +1,366 @@
1
+ import { useEffect, useSyncExternalStore, useState } from "react";
2
+ import {
3
+ definePluginApp,
4
+ experimental_useRpcQuery,
5
+ experimental_usePluginId,
6
+ useRpc,
7
+ useBbNavigate,
8
+ experimental_ThreadContextCardRow as ContextRow,
9
+ type PluginNavPanelProps,
10
+ type ExperimentalThreadContextCardProps,
11
+ } from "@get-bb/plugin-sdk/app";
12
+ import { rpcContract } from "./contract";
13
+ import type { entrySchema } from "./entries";
14
+ import type { z } from "zod";
15
+ import { Button } from "./ui/button";
16
+ import { MissionPage } from "./mission-page";
17
+ import { LearnMap } from "./map";
18
+
19
+ const listeners = new Set<() => void>();
20
+ function useLearn(poll = false) {
21
+ const pluginId = experimental_usePluginId();
22
+ const key = pluginId + ":profile";
23
+ const selected = useSyncExternalStore(
24
+ (callback) => {
25
+ listeners.add(callback);
26
+ window.addEventListener("storage", callback);
27
+ return () => {
28
+ listeners.delete(callback);
29
+ window.removeEventListener("storage", callback);
30
+ };
31
+ },
32
+ () => localStorage.getItem(key),
33
+ );
34
+ const profiles = experimental_useRpcQuery({ contract: rpcContract, method: "profiles", input: {} });
35
+ const choices = profiles.data ?? [];
36
+ const choice = choices.find((item) => item.projectId === selected) ?? choices[0];
37
+ const reading = experimental_useRpcQuery({
38
+ contract: rpcContract,
39
+ method: "reading",
40
+ input: { projectId: choice?.projectId ?? "" },
41
+ enabled: Boolean(choice),
42
+ });
43
+ useEffect(() => {
44
+ void profiles.refetch();
45
+ if (choice) void reading.refetch();
46
+ const refresh = () => {
47
+ void profiles.refetch();
48
+ if (choice) void reading.refetch();
49
+ };
50
+ window.addEventListener("focus", refresh);
51
+ const timer = poll ? window.setInterval(refresh, 10000) : undefined;
52
+ return () => {
53
+ window.removeEventListener("focus", refresh);
54
+ window.clearInterval(timer);
55
+ };
56
+ }, [choice?.projectId, poll]);
57
+ function select(projectId: string) {
58
+ localStorage.setItem(key, projectId);
59
+ for (const listener of listeners) listener();
60
+ }
61
+ return { choices, choice, select, reading, profiles };
62
+ }
63
+
64
+ function ProfilePicker() {
65
+ const { choices, choice, select } = useLearn();
66
+ const navigate = useBbNavigate();
67
+ if (!choice) return null;
68
+ return (
69
+ <select
70
+ aria-label="Profile"
71
+ className="bg-transparent text-muted-foreground text-xs max-w-full rounded-md px-2 py-1"
72
+ value={choice.projectId}
73
+ onChange={(event) => {
74
+ select(event.target.value);
75
+ navigate.toPluginPanel("learn");
76
+ }}
77
+ >
78
+ {choices.map((item) => (
79
+ <option key={item.projectId} value={item.projectId}>
80
+ {item.directory}
81
+ </option>
82
+ ))}
83
+ </select>
84
+ );
85
+ }
86
+
87
+ export function LearnPanel({ subPath }: PluginNavPanelProps) {
88
+ const { choice, reading, profiles } = useLearn();
89
+ const rpc = useRpc<typeof rpcContract>();
90
+ const navigate = useBbNavigate();
91
+ const [pending, setPending] = useState(false);
92
+ const [error, setError] = useState<string>();
93
+ async function open(intent: z.infer<typeof entrySchema>) {
94
+ if (!choice) return;
95
+ setPending(true);
96
+ setError(undefined);
97
+ try {
98
+ const result = await rpc.call("open", { projectId: choice.projectId, intent });
99
+ navigate.toThread(result.threadId);
100
+ } catch (error) {
101
+ setError(String(error));
102
+ } finally {
103
+ setPending(false);
104
+ }
105
+ }
106
+ const data = reading.data;
107
+ if (!choice)
108
+ return (
109
+ <div className="p-6 text-muted-foreground">
110
+ {profiles.error
111
+ ? profiles.error.message
112
+ : profiles.isLoading
113
+ ? "Loading Profiles…"
114
+ : "No Profiles yet. Create one with bb concept init."}
115
+ </div>
116
+ );
117
+ if (!data) return <div className="p-6 text-muted-foreground">{reading.error?.message ?? "Loading…"}</div>;
118
+ if (subPath === "map" || subPath.startsWith("map/"))
119
+ return (
120
+ <LearnMap
121
+ key={choice.projectId + subPath}
122
+ projectId={choice.projectId}
123
+ {...(subPath.length > 4 ? { mission: decodeURIComponent(subPath.slice(4)) } : {})}
124
+ dock
125
+ />
126
+ );
127
+ const missionId = subPath.startsWith("missions/") ? decodeURIComponent(subPath.slice(9)) : undefined;
128
+ return (
129
+ <div className="ncept-learn h-full overflow-auto bg-background text-foreground">
130
+ <main className="mx-auto max-w-3xl p-6 space-y-8">
131
+ {error && (
132
+ <p role="alert" className="text-destructive">
133
+ {error}
134
+ </p>
135
+ )}
136
+ {reading.error && <p role="alert">{reading.error.message}</p>}
137
+ {missionId ? (
138
+ <MissionPage
139
+ key={choice.projectId + missionId}
140
+ projectId={choice.projectId}
141
+ missionId={missionId}
142
+ sessions={data.sessions}
143
+ pending={pending}
144
+ open={open}
145
+ refreshed={() => void reading.refetch()}
146
+ />
147
+ ) : (
148
+ <>
149
+ {data.missions.filter((item) => !item.retired).length ? (
150
+ <section>
151
+ <h2 className="text-xs text-muted-foreground mb-3">Missions</h2>
152
+ <div className="rounded-xl border border-border divide-y divide-border overflow-hidden">
153
+ {data.missions
154
+ .filter((item) => !item.retired)
155
+ .map((item) => (
156
+ <div key={item.id} className="p-4 flex gap-4 items-center">
157
+ <button
158
+ className="flex-1 min-w-0 text-left"
159
+ onClick={() =>
160
+ navigate.toPluginPanel("learn", { subPath: "missions/" + encodeURIComponent(item.id) })
161
+ }
162
+ >
163
+ <div className="font-medium">{item.statement}</div>
164
+ <div className="text-xs text-muted-foreground mt-2">
165
+ {item.nodes} {item.nodes === 1 ? "Node" : "Nodes"}
166
+ {item.next ? " · next " + item.next : ""}
167
+ </div>
168
+ </button>
169
+ <Button
170
+ variant={item.active ? "default" : "outline"}
171
+ disabled={pending}
172
+ onClick={() => void open({ kind: "continue", missionId: item.id })}
173
+ >
174
+ {item.active ? "Continue →" : "Start →"}
175
+ </Button>
176
+ </div>
177
+ ))}
178
+ <button
179
+ className="w-full text-left px-4 py-3 text-muted-foreground hover:bg-accent"
180
+ disabled={pending}
181
+ onClick={() => void open({ kind: "new-mission" })}
182
+ >
183
+ + New Mission
184
+ </button>
185
+ </div>
186
+ </section>
187
+ ) : (
188
+ <section className="rounded-xl border border-border p-8 text-center">
189
+ <p className="mb-5 text-muted-foreground">
190
+ No Missions yet. Say what you want to learn in a new thread, or
191
+ </p>
192
+ <Button disabled={pending} onClick={() => void open({ kind: "new-mission" })}>
193
+ + New Mission
194
+ </Button>
195
+ </section>
196
+ )}
197
+ {data.missions.some((item) => item.retired) && (
198
+ <section className="space-y-3">
199
+ <h2 className="text-xs text-muted-foreground">Retired</h2>
200
+ {data.missions
201
+ .filter((item) => item.retired)
202
+ .map((item) => (
203
+ <button
204
+ key={item.id}
205
+ className="block text-left text-sm hover:underline"
206
+ onClick={() =>
207
+ navigate.toPluginPanel("learn", { subPath: "missions/" + encodeURIComponent(item.id) })
208
+ }
209
+ >
210
+ {item.statement}
211
+ </button>
212
+ ))}
213
+ </section>
214
+ )}
215
+ {data.dueReview.length > 0 && (
216
+ <section>
217
+ <h2 className="text-xs text-muted-foreground mb-3">Today</h2>
218
+ <div className="rounded-xl border border-border p-4 flex items-center gap-4">
219
+ <div className="flex-1">
220
+ <span>
221
+ {data.dueReview.length} {data.dueReview.length === 1 ? "card" : "cards"} due
222
+ </span>
223
+ <span className="text-muted-foreground text-sm">
224
+ {" "}
225
+ · {data.dueReview.map((item) => item.label).join(", ")}
226
+ </span>
227
+ </div>
228
+ <Button variant="outline" disabled={pending} onClick={() => void open({ kind: "review" })}>
229
+ Review →
230
+ </Button>
231
+ </div>
232
+ </section>
233
+ )}
234
+ </>
235
+ )}
236
+ </main>
237
+ </div>
238
+ );
239
+ }
240
+
241
+ function Sessions() {
242
+ const { reading } = useLearn();
243
+ const navigate = useBbNavigate();
244
+ const sessions = reading.data?.sessions.filter((item) => item.threadId) ?? [];
245
+ return (
246
+ <div className="p-2 text-sm">
247
+ {[false, true].map((closed) => (
248
+ <section key={String(closed)}>
249
+ <h2 className="px-2 py-3 text-xs text-muted-foreground">{closed ? "Closed" : "Open Sessions"}</h2>
250
+ {sessions
251
+ .filter((item) => item.closed === closed)
252
+ .map((item) => (
253
+ <button
254
+ key={item.id}
255
+ className={
256
+ "block w-full rounded-md px-2 py-2 text-left truncate hover:bg-accent " +
257
+ (item.parent ? "pl-5 " : "") +
258
+ (closed ? "text-muted-foreground" : "")
259
+ }
260
+ onClick={() => navigate.toThread(item.threadId ?? "")}
261
+ >
262
+ {item.title}
263
+ </button>
264
+ ))}
265
+ </section>
266
+ ))}
267
+ {!sessions.length && <p className="px-2 text-muted-foreground">No Sessions yet.</p>}
268
+ </div>
269
+ );
270
+ }
271
+
272
+ function SessionContext({ threadId }: ExperimentalThreadContextCardProps) {
273
+ const result = experimental_useRpcQuery({ contract: rpcContract, method: "context", input: { threadId } });
274
+ useEffect(() => {
275
+ const timer = window.setInterval(() => void result.refetch(), 10000);
276
+ return () => window.clearInterval(timer);
277
+ }, [threadId]);
278
+ const session = result.data;
279
+ if (!session) return null;
280
+ return (
281
+ <>
282
+ <ContextRow
283
+ icon="BookOpen"
284
+ label={session.mode.charAt(0).toUpperCase() + session.mode.slice(1)}
285
+ title="Session mode"
286
+ />
287
+ {session.mission && <ContextRow label={session.missionLabel ?? session.mission} title="Mission" />}
288
+ {session.nodes.length > 0 && (
289
+ <ContextRow label={session.nodes.map((node) => node.label).join(", ")} title="Node" />
290
+ )}
291
+ </>
292
+ );
293
+ }
294
+ function useBadge() {
295
+ const { reading } = useLearn(true);
296
+ const count = reading.data?.dueReview.length ?? 0;
297
+ return count ? { count, label: count + (count === 1 ? " card due" : " cards due") } : null;
298
+ }
299
+ function useLearnThread({ threadId }: { threadId: string }) {
300
+ return experimental_useRpcQuery({ contract: rpcContract, method: "threadProject", input: { threadId } }).data ?? null;
301
+ }
302
+ function ThreadMap({ threadId }: { threadId: string }) {
303
+ const projectId = useLearnThread({ threadId });
304
+ const context = experimental_useRpcQuery({ contract: rpcContract, method: "context", input: { threadId } });
305
+ if (!projectId || context.isLoading) return null;
306
+ const session = context.data;
307
+ return (
308
+ <LearnMap
309
+ key={session?.id}
310
+ projectId={projectId}
311
+ {...(session?.nodes.length || session?.mission
312
+ ? {
313
+ session: {
314
+ nodes: session.nodes.map((node) => node.id),
315
+ ...(session.mission ? { mission: session.mission } : {}),
316
+ },
317
+ }
318
+ : {})}
319
+ />
320
+ );
321
+ }
322
+ function Header({ subPath }: PluginNavPanelProps) {
323
+ const navigate = useBbNavigate();
324
+ const onMap = subPath === "map" || subPath.startsWith("map/");
325
+ const tab = (label: string, on: boolean, to: string) => (
326
+ <button
327
+ aria-current={on ? "page" : undefined}
328
+ className={"rounded px-2.5 py-0.5 " + (on ? "bg-background text-foreground shadow-sm" : "text-muted-foreground")}
329
+ onClick={() => navigate.toPluginPanel("learn", { subPath: to })}
330
+ >
331
+ {label}
332
+ </button>
333
+ );
334
+ return (
335
+ <div className="flex min-w-0 items-center gap-3">
336
+ <nav aria-label="Learn" className="inline-flex rounded-md bg-accent p-0.5 text-xs">
337
+ {tab("Overview", !onMap, "")}
338
+ {tab("Map", onMap, "map")}
339
+ </nav>
340
+ <ProfilePicker />
341
+ </div>
342
+ );
343
+ }
344
+ export default definePluginApp((app) => {
345
+ app.slots.navPanel({
346
+ id: "learn",
347
+ path: "learn",
348
+ title: "Learn",
349
+ icon: "BookOpen",
350
+ component: LearnPanel,
351
+ experimental_sidebar: Sessions,
352
+ headerContent: Header,
353
+ experimental_useBadge: useBadge,
354
+ });
355
+ app.slots.experimental_tab({
356
+ context: { kind: "thread" },
357
+ availability: "fixed",
358
+ id: "map",
359
+ title: "Map",
360
+ icon: "Network",
361
+ layout: "flush",
362
+ useVisible: (props) => useLearnThread(props) !== null,
363
+ component: ThreadMap,
364
+ });
365
+ app.slots.experimental_threadContextCardRow({ id: "session", group: "1_context", component: SessionContext });
366
+ });
@@ -0,0 +1,81 @@
1
+ import { defineRpcContract } from "@get-bb/plugin-sdk";
2
+ import { z } from "zod";
3
+ import { entrySchema } from "./entries";
4
+ import { learningReading, mapReading, profileChoice } from "./reading";
5
+ import { missionReading } from "./mission-reading";
6
+
7
+ // The request travels through a host-local temporary file, so a full carry never
8
+ // has to fit an OS argument or bb CLI's single-line stdin limit.
9
+ export const handoffSchema = z.object({
10
+ session: z.string().min(1),
11
+ mode: z.string().min(1),
12
+ kickoff: z.string().optional(),
13
+ learnerKickoff: z.boolean().optional(),
14
+ carry: z
15
+ .string()
16
+ .max(4 * 1024 * 1024)
17
+ .optional(),
18
+ aside: z.boolean(),
19
+ });
20
+ const retirement = z.object({ missionId: z.string(), outcome: z.enum(["achieved", "abandoned"]) });
21
+ const sessionDescription = z.object({ session: z.string(), mode: z.string(), title: z.string() });
22
+ export const rpcContract = defineRpcContract({
23
+ retire: { input: retirement.extend({ projectId: z.string() }), output: z.object({}), tags: () => ["learning"] },
24
+ share: {
25
+ input: z.object({ projectId: z.string(), missionId: z.string(), title: z.string().min(1) }),
26
+ output: z.object({ url: z.string() }),
27
+ },
28
+ profiles: { input: z.object({}), output: z.array(profileChoice) },
29
+ mission: {
30
+ input: z.object({ projectId: z.string(), missionId: z.string() }),
31
+ output: missionReading,
32
+ tags: () => ["learning"],
33
+ },
34
+ reading: { input: z.object({ projectId: z.string() }), output: learningReading, tags: () => ["learning"] },
35
+ map: {
36
+ input: z.object({ projectId: z.string(), missionId: z.string().optional() }),
37
+ output: mapReading,
38
+ tags: () => ["learning"],
39
+ },
40
+ context: {
41
+ input: z.object({ threadId: z.string() }),
42
+ output: learningReading.shape.sessions.element.nullable(),
43
+ tags: () => ["learning"],
44
+ },
45
+ threadProject: { input: z.object({ threadId: z.string() }), output: z.string().nullable() },
46
+ open: {
47
+ input: z.object({ projectId: z.string(), intent: entrySchema }).strict(),
48
+ output: z.object({ threadId: z.string(), title: z.string() }),
49
+ },
50
+ thread: {
51
+ input: z.object({ projectId: z.string(), session: z.string() }).strict(),
52
+ output: z.object({ threadId: z.string().nullable() }),
53
+ },
54
+ });
55
+ export const hostContract = defineRpcContract({
56
+ retire: { input: retirement.extend({ directory: z.string() }), output: z.object({}) },
57
+ share: {
58
+ input: z.object({ directory: z.string(), missionId: z.string(), title: z.string().min(1) }),
59
+ output: z.object({ url: z.string() }),
60
+ },
61
+ recognize: { input: z.object({ directory: z.string() }), output: z.boolean() },
62
+ mission: { input: z.object({ directory: z.string(), missionId: z.string() }), output: missionReading },
63
+ reading: { input: z.object({ directory: z.string() }), output: learningReading },
64
+ map: { input: z.object({ directory: z.string(), missionId: z.string().optional() }), output: mapReading },
65
+ entry: {
66
+ input: z.object({ directory: z.string(), intent: entrySchema }),
67
+ output: z.object({ title: z.string(), resume: z.string().optional() }),
68
+ },
69
+ session: {
70
+ input: z.object({ directory: z.string(), session: z.string() }),
71
+ output: sessionDescription,
72
+ },
73
+ init: {
74
+ input: z.object({ directory: z.string(), source: z.string().optional() }),
75
+ output: z.object({ directory: z.string() }),
76
+ },
77
+ handoff: {
78
+ input: z.object({ directory: z.string(), requestFile: z.string() }),
79
+ output: handoffSchema.extend({ title: z.string() }),
80
+ },
81
+ });
package/src/entries.ts ADDED
@@ -0,0 +1,32 @@
1
+ import { z } from "zod";
2
+
3
+ export const skipStop = z.object({
4
+ kind: z.string(),
5
+ number: z.number(),
6
+ checkpoint: z
7
+ .object({
8
+ milestone: z
9
+ .custom<`node-${string}`>((value) => typeof value === "string" && value.startsWith("node-"))
10
+ .optional(),
11
+ required: z.boolean(),
12
+ final: z.literal(true).optional(),
13
+ })
14
+ .optional(),
15
+ });
16
+
17
+ export const entrySchema = z.discriminatedUnion("kind", [
18
+ z.object({ kind: z.literal("skip-lesson"), missionId: z.string().min(1) }).strict(),
19
+ z.object({ kind: z.literal("skip-to"), missionId: z.string().min(1), stop: skipStop }).strict(),
20
+ z.object({ kind: z.literal("continue"), missionId: z.string().min(1) }).strict(),
21
+ z.object({ kind: z.literal("new-mission") }).strict(),
22
+ z.object({ kind: z.literal("review") }).strict(),
23
+ z
24
+ .object({
25
+ kind: z.literal("tell-tutor"),
26
+ missionId: z.string().min(1),
27
+ request: z.string().refine((value) => value.trim().length > 0, "Tell the tutor what you want to change"),
28
+ })
29
+ .strict(),
30
+ z.object({ kind: z.literal("revise-lesson"), missionId: z.string().min(1) }).strict(),
31
+ z.object({ kind: z.literal("revise-route"), missionId: z.string().min(1) }).strict(),
32
+ ]);