@mmon-co/ncept-pi 0.0.0-stage → 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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 mmon-co
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,56 @@
1
- # Temporary Holding Version
1
+ # @mmon-co/ncept-pi
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The official pi learning front end over the MIT-licensed [local Profile host](../local/README.md). Your Profile is an ordinary directory; pi's accounts, models, theme, keybindings and global extensions stay yours. Coding projects do not load this package.
4
+
5
+ ## Start learning
6
+
7
+ Install [pi](https://pi.dev), then:
8
+
9
+ ```sh
10
+ npx @mmon-co/ncept-pi init ~/learn
11
+ cd ~/learn
12
+ pi
13
+ ```
14
+
15
+ Accept pi's one-time project trust prompt. The dashboard above the editor shows Missions, next stops and due review, and clears when you speak. A fresh conversation is a chat Session.
16
+
17
+ - `/learn <goal>` charts what you want to learn. `/learn` offers Missions and their next stops; `/learn <mission-id>` opens a particular Mission.
18
+ - `/skip` in a Mission Lesson skips this Lesson or ahead to a later planned stop, recording the skipped Nodes as claimed known.
19
+ - `/review` opens the due review batch; `/author [goal]` opens an authoring Session.
20
+ - `/missions` shows the dashboard again.
21
+ - `/hub pull <release-url or patch@version>` adopts a release without an account. You can also paste an address and ask the tutor to pull it.
22
+ - `/ncept login` signs in once through the browser; `/ncept logout` removes the saved Common Concept credential. These are separate from pi's model accounts.
23
+ - In authoring, ask the tutor to publish: its `hub` tool packages the current personal Patch, bases and Materials and confirms public publication. Publishing needs a free Common Concept account, not a subscription.
24
+ - `/ncept export-to-web` replaces web Main with this Profile after confirmation (and, if needed, choosing the Missions that fit the web allowance).
25
+ - `/ncept import-from-web` replaces this Profile after confirmation, preserving the old project in the host's backup directory. pi project settings are restored; `/resume` can continue imported Sessions.
26
+
27
+ Every conversation is pi's own JSONL under `sessions/`. `/resume` continues one, `/tree` selects its branch, and `/new` starts a fresh chat. Host mode switches open next or aside pi Sessions with the Theory's declared carry. Observations, Mission progress, saved Materials and trusted Session associations live in the Profile and travel with its exchange archive. A session pi keeps elsewhere (`--session-dir`, `PI_CODING_AGENT_SESSION_DIR`, or a front end such as bb's pi bridge) is mirrored into `sessions/`, so the Profile still carries every transcript.
28
+
29
+ The mode's native tools, context and Skills replace pi's coding prompt every turn. Global `AGENTS.md` and coding Skills are excluded. Existing web/search tools remain available in modes mounting `web`, and shell/file-writing tools in modes mounting `bash`. Tool selection is a tutor capability boundary, not an operating-system sandbox: pi and its extensions still have your OS permissions.
30
+
31
+ Models and grading use the model currently selected in pi, through pi's provider/auth runtime. The selected model must support tool calls and structured judgments. No Common Concept account, token limit, hosted deployment or subscription is needed for local learning.
32
+
33
+ ## Front ends over this extension
34
+
35
+ A front end layered over pi can own where Sessions open, a new window or thread per Session say, through pi's shared extension bus. When a Session opens while the current pi session already holds a conversation, the extension emits `ncept:open-session` with the opened Session, its kickoff message, its hidden carry and whether it is aside; a listener that calls `claim` opens it itself, and the current pi session stays visible for the learner to archive. Its next message resumes its previous host Session before the turn. The claimant can return a learner-facing continuation (a link, for example); a tutor-requested switch returns it in the tool result so the tutor can finish the outgoing turn normally. In the fresh pi session, the front end emits `ncept:adopt-session` with the Session and carry before the first prompt. For a learner control without an outgoing conversation, emit `ncept:begin-session` after this extension's `session_start`, supplying a local-host `SessionIntent` and a `claim` callback. Await the claimed function before the first prompt; it resolves the intent and records the Session in pi. The channels and payload types are exported from `@mmon-co/ncept-pi/events`.
36
+
37
+ ## Development first use
38
+
39
+ From a repository checkout:
40
+
41
+ ```sh
42
+ bun install
43
+ bun run --cwd packages/pi build
44
+ bun packages/pi/scripts/first-use.ts /tmp/my-ncept-profile
45
+ cd /tmp/my-ncept-profile && pi
46
+ ```
47
+
48
+ The setup script requires an unused directory and points the project package at this checkout instead of the unpublished npm package. It creates an empty Profile, no account or seed; pi uses your existing model authentication. It does not change your global pi settings or deploy a service.
49
+
50
+ ```sh
51
+ bun test packages/pi/test/pi-wiring.test.ts
52
+ ```
53
+
54
+ The SDK wiring smoke uses a scripted model with real host tools and pi Session files; it makes no paid or network requests.
55
+
56
+ For a checkout-owned hosted endpoint, set `NCEPT_HUB_URL` to its Application base URL (including `/ncept`) before starting pi. `NCEPT_CREDENTIALS_FILE` selects an isolated credential file outside the Profile; login and logout use the same file. Omit both for the public product. OAuth uses pi's public CIMD identity, PKCE and the `patches publish learn` scopes; it does not require the issuer to enable dynamic registration.
package/dist/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
package/dist/cli.js ADDED
@@ -0,0 +1,21 @@
1
+ #!/usr/bin/env node
2
+ import { initProject } from "./init.js";
3
+ const [command, directory, ...extra] = process.argv.slice(2);
4
+ if (command !== "init" || !directory || extra.length) {
5
+ console.error("Usage: npx @mmon-co/ncept-pi init <dir>");
6
+ process.exitCode = 1;
7
+ }
8
+ else {
9
+ try {
10
+ const dir = await initProject(directory);
11
+ console.log("Profile ready: " +
12
+ dir +
13
+ "\nRun: cd " +
14
+ JSON.stringify(dir) +
15
+ " && pi\nTrust this learning project when pi asks.");
16
+ }
17
+ catch (error) {
18
+ console.error(error instanceof Error ? error.message : String(error));
19
+ process.exitCode = 1;
20
+ }
21
+ }
@@ -0,0 +1,43 @@
1
+ import type { HostSession, SessionIntent } from "@mmon-co/ncept-local";
2
+ /**
3
+ * Channels on pi's shared extension bus (`pi.events`) that let another front end
4
+ * layered over this extension (a bb thread per Session, say) own where Sessions open.
5
+ */
6
+ /**
7
+ * Emitted when the tutor or a command opens a host Session while the current pi
8
+ * session already holds a conversation. A listener that calls `claim` opens it
9
+ * elsewhere; otherwise this extension starts a new pi session in-process.
10
+ */
11
+ export declare const OPEN_SESSION = "ncept:open-session";
12
+ export type OpenSession = {
13
+ /** The opened host Session, already recorded in the Profile. */
14
+ readonly session: string;
15
+ readonly mode: string;
16
+ /** Starting text for the new conversation. */
17
+ readonly kickoff?: string;
18
+ /** The learner supplied this text, rather than a host continuation. */
19
+ readonly learnerKickoff?: boolean;
20
+ /** Context the next tutor needs from this conversation, hidden from the learner. */
21
+ readonly carry?: string;
22
+ /** The previous Session stays open beside the new one. */
23
+ readonly aside: boolean;
24
+ /** Take over opening; return a learner-facing continuation for the tutor's tool result.
25
+ * A rejection closes the new Session and keeps the current one. */
26
+ claim(open: () => Promise<void | string>): void;
27
+ };
28
+ /**
29
+ * Emitted by the claiming front end in a fresh pi session, before its first prompt,
30
+ * to continue a claimed host Session there.
31
+ */
32
+ export declare const ADOPT_SESSION = "ncept:adopt-session";
33
+ export type AdoptSession = {
34
+ readonly session: string;
35
+ readonly carry?: string;
36
+ };
37
+ /** A front end starts a fresh conversation from a learner entry, after session_start.
38
+ * The tutoring extension alone resolves the entry and writes the Profile. */
39
+ export declare const BEGIN_SESSION = "ncept:begin-session";
40
+ export type BeginSession = {
41
+ readonly intent: SessionIntent;
42
+ claim(begin: () => Promise<HostSession>): void;
43
+ };
package/dist/events.js ADDED
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Channels on pi's shared extension bus (`pi.events`) that let another front end
3
+ * layered over this extension (a bb thread per Session, say) own where Sessions open.
4
+ */
5
+ /**
6
+ * Emitted when the tutor or a command opens a host Session while the current pi
7
+ * session already holds a conversation. A listener that calls `claim` opens it
8
+ * elsewhere; otherwise this extension starts a new pi session in-process.
9
+ */
10
+ export const OPEN_SESSION = "ncept:open-session";
11
+ /**
12
+ * Emitted by the claiming front end in a fresh pi session, before its first prompt,
13
+ * to continue a claimed host Session there.
14
+ */
15
+ export const ADOPT_SESSION = "ncept:adopt-session";
16
+ /** A front end starts a fresh conversation from a learner entry, after session_start.
17
+ * The tutoring extension alone resolves the entry and writes the Profile. */
18
+ export const BEGIN_SESSION = "ncept:begin-session";
@@ -0,0 +1,3 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ /** One extension instance belongs to one pi session, including after /resume. */
3
+ export default function ncept(pi: ExtensionAPI): void;