@muha-sdk/pi-adapter 0.0.0-stage → 0.1.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gao Sijie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# @muha-sdk/pi-adapter
 
-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.
+Pi uses the verified high-level input patch for SDK 1.0.4. See
+[qualification and limitations](https://github.com/Gao-Sijie/muha/blob/main/QUALIFICATION.md)
+for source versions and acceptance. The older Pi/Pi grilling result belongs to
+SDK 0.84.2 and does not qualify SDK 1.0.4.
+
+```ts
+import { createMuhaRuntime } from "@muha-sdk/core";
+import { piAdapter } from "@muha-sdk/pi-adapter";
+
+const runtime = await createMuhaRuntime({ harnesses: [piAdapter()] });
+try {
+  const session = await runtime.createSession({
+    harness: "pi",
+    workspacePath: "/absolute/project",
+    model: "provider/model",
+    approvalPolicy: "autoApprove",
+  });
+  const turn = await session.startTurn([{ type: "text", text: "Explain this project." }]);
+  for await (const event of turn) console.log(event);
+  console.log(await turn.result);
+} finally {
+  await runtime.close();
+}
+```
+
+## Native configuration and execution
+
+Pi declares the exact official SDK version `@earendil-works/pi-coding-agent@1.0.4`
+as a normal npm dependency; it does not bundle the SDK tree. It is not a PATH
+CLI or a globally installed SDK. Installing this Adapter needs Registry access or
+a prewarmed npm cache. Callers supply native Pi authentication and
+model configuration. `OfficialAdapterOptions.env` can override or delete child
+environment variables, including Pi's `PI_CODING_AGENT_DIR`; it never changes
+the host environment or working directory. Node.js 22.20.0 or newer is required.
+
+Each Session handle owns an SDK process. Initialization and native listing use
+short-lived owned processes; only the consumer's main process owns the Muha
+Runtime and Diagnostic Event Store. This is lifecycle isolation, not a sandbox.
+Unexpected owned-process loss closes the whole Runtime; native history can
+be explicitly resumed through a new Runtime. Closing handles does not delete it.
+
+Session IDs, listing and parsing belong to native SessionManager. Listings
+include external native sessions and can target deleted Workspaces. SDK default
+skipping of damaged records and silent handling of directory/file read errors
+are accepted, as explicitly approved on 2026-09-08. An empty listing is the SDK's
+result, not proof that physical storage contains no sessions. Muha does not add
+an integrity checker or file parser. Returned identities and Workspaces remain
+validated; explicit SDK errors propagate, and missing references never become
+new Sessions.
+
+Model IDs use `provider/model`; effort values are native and model-dependent.
+Create/resume and idle setters verify the SDK's effective selection. Run
+selections do not change persistent defaults. Native history/authentication,
+authorized tool/extension configuration writes and native reload remain intact.
+Whole-execution SDK retry stays disabled so Core owns the Turn retry budget.
+Retries are at-least-once: native history, tools and external side effects can
+repeat. No exactly-once execution, transactional rollback or transparent
+recovery of an interrupted Turn is promised.
+
+Private diagnostic records distinguish SDK event callbacks, extension errors,
+native listing results and model-fallback warnings by source. Only the host
+writes the store; SDK runtime/auth objects, logs and Adapter IPC acknowledgements
+are not native evidence. Retained semantic payloads can contain sensitive content
+and remain subject to Core's unredacted storage and caller-managed retention.
+
+## Capabilities and boundaries
+
+The static Profile supports ordered text/images, native listing, Workspace
+Skills, model/effort selection, streaming messages/reasoning, tools and usage.
+The current qualification status is recorded in
+`QUALIFICATION.md` in the source repository.
+
+- Explicitly select `autoApprove` or `harnessManaged`. Pi has no built-in approval
+  gate; neither policy manufactures Approval events or bypasses native denials.
+  `interactive`, `autoDeny` and omitted policy (which defaults to `interactive`)
+  reject before execution.
+- Submit the ordinary ordered Turn Input array. File/base64 images are converted
+  inside this Adapter; consumers need no Pi-specific ordering metadata. A bounded
+  high-level SDK patch preserves normal user-message persistence and lifecycle.
+  Explicit native input transformations and Skill/template expansion retain their
+  native replacement semantics. Pi 1.x also decodes and normalizes images; native omissions or normalization hints produce its replacement message. Image-only input is valid; PNG/JPEG/WebP/GIF are
+  the supported Muha media types.
+- Workspace Skills use the native `.pi/skills` target. Pi can install and load
+  native extensions, including MCP extensions, independently of Muha.
+  `workspaceMcp` and `turnQuestions` remain false; configuring Pi MCP through Muha
+  fails and unsupported native UI is not answered on the caller's behalf.
+- Unsupported extension interaction fails with cleanup; an extension that never
+  settles after that error is bounded by process termination and Runtime closure.
+  Arbitrary third-party extension compatibility and Session replacement from
+  native extension commands are not promised.
+
+## Building
+
+`npm run build --workspace @muha-sdk/pi-adapter` builds the TypeScript host and
+verified input patch from the repository's locked SDK installation. `npm pack`
+only verifies the prepared patch and fails if worker sources or the patch are
+missing/stale; it does not rewrite an SDK tree used by live processes. The
+resulting tarball contains the patch manifest, private workers and Pi upstream
+MIT license, but not the SDK dependency tree. npm installs the exact SDK version
+as an ordinary dependency. No consumer install script is needed.
+
+Owned SDK processes run under the Linux subreaper shipped by the exact Core
+dependency. Session and Runtime closure reclaim native detached Bash processes,
+including children whose PID the SDK has not yet reported. A lost ownership helper
+or cleanup timeout produces an error; it does not prove descendant reclamation.

package/dist/PI-SDK-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { HarnessRegistration, OfficialAdapterOptions } from "@muha-sdk/core";
+export type { OfficialAdapterOptions } from "@muha-sdk/core";
+export declare function piAdapter(options?: OfficialAdapterOptions): HarnessRegistration;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuB,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAevG,YAAY,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,wBAAgB,SAAS,CAAC,OAAO,GAAE,sBAA2B,GAAG,mBAAmB,CAKnF"}

package/dist/index.js

@@ -0,0 +1,19 @@
+import { createOfficialHarnessRegistration, createSkillsCliPlanner } from "@muha-sdk/core/internal";
+import { PiProcess } from "./pi-process.js";
+// Stage-four target Profile. The complete suites and real-Harness gates in #85
+// must pass before this development package can be formally admitted.
+const capabilities = Object.freeze({
+    sessionListing: true, imageInput: true,
+    approvalPolicies: Object.freeze(["autoApprove", "harnessManaged"]),
+    turnQuestions: false, workspaceSkills: true, workspaceMcp: false,
+    model: Object.freeze({ selectionAt: Object.freeze(["createSession", "resumeSession", "idleSession"]), observation: "effective" }),
+    effort: Object.freeze({ selectionAt: Object.freeze(["createSession", "resumeSession", "idleSession"]), observation: "effective", requiresKnownModel: true }),
+    assistantMessageStreaming: true, assistantReasoningStreaming: true, toolEvents: true, turnUsage: true,
+});
+export function piAdapter(options = {}) {
+    return createOfficialHarnessRegistration("pi", options, capabilities, {
+        planSkill: createSkillsCliPlanner("pi"),
+        planMcpServer() { throw new Error("Pi Workspace MCP is not supported"); },
+    }, (snapshot, context) => new PiProcess(snapshot, context));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iCAAiC,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,+EAA+E;AAC/E,sEAAsE;AACtE,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC;IACjC,cAAc,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI;IACtC,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,EAAE,gBAAgB,CAAU,CAAC;IAC3E,aAAa,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK;IAChE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,eAAe,EAAE,eAAe,EAAE,aAAa,CAAU,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;IAC1I,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,eAAe,EAAE,eAAe,EAAE,aAAa,CAAU,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC;IACrK,yBAAyB,EAAE,IAAI,EAAE,2BAA2B,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI;CACxE,CAAC,CAAC;AAGjC,MAAM,UAAU,SAAS,CAAC,UAAkC,EAAE;IAC5D,OAAO,iCAAiC,CAAC,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE;QACpE,SAAS,EAAE,sBAAsB,CAAC,IAAI,CAAC;QACvC,aAAa,KAAK,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC,CAAC,CAAC;KAC1E,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAC9D,CAAC"}