@papert-code/papert-code 0.3.92 → 0.3.94

package/README.md

@@ -1,18 +1,21 @@
 # Papert Code
 
-Papert Code is a terminal-native AI coding companion that automates everyday developer workflows. It reads, edits, and generates code across large repositories, automates shell tasks with safety rails, and exposes the same capabilities through a TypeScript SDK and a VS Code companion extension.
+![Papert Terminal UI](docs/assets/papert-screenshot.png)
+
+Papert Code is an AI agent engine for software engineering workflows. It plans, reads, edits, and generates code across large repositories, executes shell and tool actions with safety controls, and exposes the same agent runtime through TypeScript and Python SDKs plus a VS Code companion extension.
 
 - Terminal-first agent with `papert`, built for high-signal, multi-turn coding sessions.
 - Codebase-aware tools: reads and edits files, runs ripgrep queries, executes shell commands, and respects `.gitignore` + `.papertignore`.
 - Safety and control: structured plans, explicit approval modes (`plan`, `default`, `auto-edit`, `yolo`), and sandbox support (Seatbelt/macOS, Docker, Podman).
-- Extensible platform: user commands, subagents, Model Context Protocol (MCP) servers, and a TypeScript SDK for embedding Papert Code into your own apps.
+- Extensible platform: user commands, subagents, Model Context Protocol (MCP) servers, and TypeScript/Python SDKs for embedding Papert Code into your own apps.
 - Works with any OpenAI-compatible API; pick your own model, base URL, and keys.
 
 ## Repository layout
 
 - `packages/cli` — the Papert Code CLI (interactive TUI, tools, settings, sandbox integration).
 - `packages/core` — core tool implementations, MCP plumbing, and shared services.
-- `packages/sdk-typescript` — programmatic access to Papert Code (streaming queries + full CLI runner).
+- `packages/sdk-typescript` — programmatic TypeScript SDK (streaming queries, reusable sessions, full CLI runner).
+- `packages/sdk-python` — programmatic Python SDK (streaming queries, reusable sessions, control APIs).
 - `packages/test-utils` — helpers for integration/terminal tests.
 - `packages/vscode-ide-companion` — VS Code extension that mirrors the CLI features inside the editor.
 - `docs/` — user and contributor documentation.
@@ -66,6 +69,27 @@ papert
 > Generate integration tests for the payment flow.
 ```
 
+## Interface preview
+
+![Papert Web UI](docs/assets/papert-web.png)
+
+How to access:
+
+- **Terminal UI**: run `papert` in your project directory.
+- **Web UI**: run with remote/web env enabled and open `http://localhost:41242`.
+
+Example Web UI environment profile:
+
+```bash
+export PAPERT_REMOTE_ENABLED=1
+export PAPERT_REMOTE_SERVER_TOKEN=hi
+export PAPERT_REMOTE_SESSION_TTL_MS=300000
+export CODER_AGENT_PORT=41242
+export PAPERT_REMOTE_DOCS_ENABLED=1
+export PAPERT_SHARE_PUBLIC_URL_BASE=http://localhost:41242
+papert server --host 0.0.0.0 --port 41242 --docs
+```
+
 ## Remote driving (daemon/client)
 
 Papert Code supports an optional remote-driving mode where you run a daemon on one machine (or container/VM) and connect to it from another machine.
@@ -142,6 +166,9 @@ Install the SDK:
 npm install @papert-code/sdk-typescript
 ```
 
+The SDK package includes `@papert-code/papert-code` as a dependency, so most
+users do not need to install the CLI separately for SDK usage.
+
 ### Streaming queries
 
 ```typescript
@@ -182,15 +209,84 @@ const { stdout, exitCode } = await agent.runPrompt(
 console.log(stdout, exitCode);
 ```
 
+### Reusable sessions (high-level client)
+
+```typescript
+import { createClient } from '@papert-code/sdk-typescript';
+
+const client = createClient({
+  cwd: '/path/to/project',
+  permissionMode: 'auto-edit',
+});
+
+const session = client.createSession({ sessionId: 'demo-session' });
+await session.send('Create TODO.md with 3 items');
+await session.send('Now summarize TODO.md');
+await client.close();
+```
+
 SDK features:
 
 - Multi-turn streaming API with tool awareness.
+- High-level session API (`createClient`, `session.send`, `session.stream`).
 - Permission hooks (`canUseTool`), custom tool allow/deny lists, and MCP server wiring.
 - Abort support via `AbortController`, per-call environment overrides, and subagent configuration.
 - Works with the installed `papert` binary or a specified CLI path.
 
 Examples live under `packages/sdk-typescript/examples` (ESM, no ts-node required).
 
+TypeScript SDK docs:
+
+- `docs/cli/sdk-typescript.md`
+- `docs/cli/sdk-typescript-multi-agent-skills.md`
+
+## Python SDK
+
+Install the SDK:
+
+```bash
+pip install papert-code-sdk
+```
+
+### Streaming query
+
+```python
+import asyncio
+from papert_code_sdk import query
+
+async def main():
+    result = query(
+        prompt="List top-level folders in this repo",
+        options={"cwd": "/path/to/project"},
+    )
+    async for message in result:
+        if message.type == "assistant":
+            print(message.message.content)
+
+asyncio.run(main())
+```
+
+### Reusable sessions (high-level client)
+
+```python
+import asyncio
+from papert_code_sdk import create_client
+
+async def main():
+    client = create_client({"cwd": "/path/to/project", "permissionMode": "auto-edit"})
+    session = client.create_session(session_id="demo-session")
+    await session.send("Create TODO.md with 3 items")
+    await session.send("Now summarize TODO.md")
+    await client.close()
+
+asyncio.run(main())
+```
+
+Python SDK docs:
+
+- `docs/cli/sdk-python.md`
+- `docs/cli/sdk-python-multi-agent-skills.md`
+
 ## VS Code companion
 
 `packages/vscode-ide-companion` mirrors the CLI experience inside VS Code: native diffing, context awareness, and the same approval modes. Build it with `npm run build:vscode` or install from the marketplace once published.

package/dist/chunks/{chunk-G2NP25TN.js → chunk-2MUETKKX.js}

@@ -1,11 +1,28 @@
 // Force strict mode and setup for ESM
 "use strict";
+const __papertOriginalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = function patchedEmitWarning(warning, ...args) {
+  if (!process.env.PAPERT_SHOW_NODE_DEPRECATIONS) {
+    const warningCode =
+      (warning && typeof warning === 'object' && 'code' in warning && warning.code) ||
+      (args.length > 1 && typeof args[1] === 'string' && args[1]) ||
+      (args.length > 0 &&
+        args[0] &&
+        typeof args[0] === 'object' &&
+        'code' in args[0] &&
+        args[0].code);
+    if (warningCode === 'DEP0040' || warningCode === 'DEP0169') {
+      return;
+    }
+  }
+  return __papertOriginalEmitWarning(warning, ...args);
+};
 import {
   __esm,
   __export,
   __name,
   init_esbuild_shims
-} from "./chunk-4HTLIVVR.js";
+} from "./chunk-NCFEMX7E.js";
 
 // node_modules/@opentelemetry/api/build/esm/platform/node/globalThis.js
 var _globalThis;

package/dist/chunks/{chunk-P4DPKRC2.js → chunk-423NGIST.js}

@@ -1,11 +1,28 @@
 // Force strict mode and setup for ESM
 "use strict";
+const __papertOriginalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = function patchedEmitWarning(warning, ...args) {
+  if (!process.env.PAPERT_SHOW_NODE_DEPRECATIONS) {
+    const warningCode =
+      (warning && typeof warning === 'object' && 'code' in warning && warning.code) ||
+      (args.length > 1 && typeof args[1] === 'string' && args[1]) ||
+      (args.length > 0 &&
+        args[0] &&
+        typeof args[0] === 'object' &&
+        'code' in args[0] &&
+        args[0].code);
+    if (warningCode === 'DEP0040' || warningCode === 'DEP0169') {
+      return;
+    }
+  }
+  return __papertOriginalEmitWarning(warning, ...args);
+};
 import {
   __commonJS,
   __name,
   __require,
   init_esbuild_shims
-} from "./chunk-4HTLIVVR.js";
+} from "./chunk-NCFEMX7E.js";
 
 // node_modules/undici/lib/core/symbols.js
 var require_symbols = __commonJS({

package/dist/chunks/{chunk-OVTXUA3U.js → chunk-4YLWLT76.js}

@@ -1,126 +1,26 @@
 // Force strict mode and setup for ESM
 "use strict";
+const __papertOriginalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = function patchedEmitWarning(warning, ...args) {
+  if (!process.env.PAPERT_SHOW_NODE_DEPRECATIONS) {
+    const warningCode =
+      (warning && typeof warning === 'object' && 'code' in warning && warning.code) ||
+      (args.length > 1 && typeof args[1] === 'string' && args[1]) ||
+      (args.length > 0 &&
+        args[0] &&
+        typeof args[0] === 'object' &&
+        'code' in args[0] &&
+        args[0].code);
+    if (warningCode === 'DEP0040' || warningCode === 'DEP0169') {
+      return;
+    }
+  }
+  return __papertOriginalEmitWarning(warning, ...args);
+};
 import {
   __name,
   init_esbuild_shims
-} from "./chunk-4HTLIVVR.js";
-
-// packages/core/dist/src/utils/errors.js
-init_esbuild_shims();
-function isNodeError(error) {
-  return error instanceof Error && "code" in error;
-}
-__name(isNodeError, "isNodeError");
-function getErrorMessage(error) {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  try {
-    return String(error);
-  } catch {
-    return "Failed to get error details";
-  }
-}
-__name(getErrorMessage, "getErrorMessage");
-var FatalError = class extends Error {
-  static {
-    __name(this, "FatalError");
-  }
-  exitCode;
-  constructor(message, exitCode) {
-    super(message);
-    this.exitCode = exitCode;
-  }
-};
-var FatalAuthenticationError = class extends FatalError {
-  static {
-    __name(this, "FatalAuthenticationError");
-  }
-  constructor(message) {
-    super(message, 41);
-  }
-};
-var FatalInputError = class extends FatalError {
-  static {
-    __name(this, "FatalInputError");
-  }
-  constructor(message) {
-    super(message, 42);
-  }
-};
-var FatalSandboxError = class extends FatalError {
-  static {
-    __name(this, "FatalSandboxError");
-  }
-  constructor(message) {
-    super(message, 44);
-  }
-};
-var FatalConfigError = class extends FatalError {
-  static {
-    __name(this, "FatalConfigError");
-  }
-  constructor(message) {
-    super(message, 52);
-  }
-};
-var FatalTurnLimitedError = class extends FatalError {
-  static {
-    __name(this, "FatalTurnLimitedError");
-  }
-  constructor(message) {
-    super(message, 53);
-  }
-};
-var FatalCancellationError = class extends FatalError {
-  static {
-    __name(this, "FatalCancellationError");
-  }
-  constructor(message) {
-    super(message, 130);
-  }
-};
-var ForbiddenError = class extends Error {
-  static {
-    __name(this, "ForbiddenError");
-  }
-};
-var UnauthorizedError = class extends Error {
-  static {
-    __name(this, "UnauthorizedError");
-  }
-};
-var BadRequestError = class extends Error {
-  static {
-    __name(this, "BadRequestError");
-  }
-};
-function toFriendlyError(error) {
-  if (error && typeof error === "object" && "response" in error) {
-    const gaxiosError = error;
-    const data = parseResponseData(gaxiosError);
-    if (data.error && data.error.message && data.error.code) {
-      switch (data.error.code) {
-        case 400:
-          return new BadRequestError(data.error.message);
-        case 401:
-          return new UnauthorizedError(data.error.message);
-        case 403:
-          return new ForbiddenError(data.error.message);
-        default:
-      }
-    }
-  }
-  return error;
-}
-__name(toFriendlyError, "toFriendlyError");
-function parseResponseData(error) {
-  if (typeof error.response?.data === "string") {
-    return JSON.parse(error.response?.data);
-  }
-  return error.response?.data;
-}
-__name(parseResponseData, "parseResponseData");
+} from "./chunk-NCFEMX7E.js";
 
 // node_modules/open/index.js
 init_esbuild_shims();
@@ -619,10 +519,126 @@ defineLazyProperty(apps, "browser", () => "browser");
 defineLazyProperty(apps, "browserPrivate", () => "browserPrivate");
 var open_default = open;
 
+// packages/core/dist/src/utils/errors.js
+init_esbuild_shims();
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+__name(isNodeError, "isNodeError");
+function getErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  try {
+    return String(error);
+  } catch {
+    return "Failed to get error details";
+  }
+}
+__name(getErrorMessage, "getErrorMessage");
+var FatalError = class extends Error {
+  static {
+    __name(this, "FatalError");
+  }
+  exitCode;
+  constructor(message, exitCode) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+};
+var FatalAuthenticationError = class extends FatalError {
+  static {
+    __name(this, "FatalAuthenticationError");
+  }
+  constructor(message) {
+    super(message, 41);
+  }
+};
+var FatalInputError = class extends FatalError {
+  static {
+    __name(this, "FatalInputError");
+  }
+  constructor(message) {
+    super(message, 42);
+  }
+};
+var FatalSandboxError = class extends FatalError {
+  static {
+    __name(this, "FatalSandboxError");
+  }
+  constructor(message) {
+    super(message, 44);
+  }
+};
+var FatalConfigError = class extends FatalError {
+  static {
+    __name(this, "FatalConfigError");
+  }
+  constructor(message) {
+    super(message, 52);
+  }
+};
+var FatalTurnLimitedError = class extends FatalError {
+  static {
+    __name(this, "FatalTurnLimitedError");
+  }
+  constructor(message) {
+    super(message, 53);
+  }
+};
+var FatalCancellationError = class extends FatalError {
+  static {
+    __name(this, "FatalCancellationError");
+  }
+  constructor(message) {
+    super(message, 130);
+  }
+};
+var ForbiddenError = class extends Error {
+  static {
+    __name(this, "ForbiddenError");
+  }
+};
+var UnauthorizedError = class extends Error {
+  static {
+    __name(this, "UnauthorizedError");
+  }
+};
+var BadRequestError = class extends Error {
+  static {
+    __name(this, "BadRequestError");
+  }
+};
+function toFriendlyError(error) {
+  if (error && typeof error === "object" && "response" in error) {
+    const gaxiosError = error;
+    const data = parseResponseData(gaxiosError);
+    if (data.error && data.error.message && data.error.code) {
+      switch (data.error.code) {
+        case 400:
+          return new BadRequestError(data.error.message);
+        case 401:
+          return new UnauthorizedError(data.error.message);
+        case 403:
+          return new ForbiddenError(data.error.message);
+        default:
+      }
+    }
+  }
+  return error;
+}
+__name(toFriendlyError, "toFriendlyError");
+function parseResponseData(error) {
+  if (typeof error.response?.data === "string") {
+    return JSON.parse(error.response?.data);
+  }
+  return error.response?.data;
+}
+__name(parseResponseData, "parseResponseData");
+
 export {
   isNodeError,
   getErrorMessage,
-  FatalError,
   FatalAuthenticationError,
   FatalInputError,
   FatalSandboxError,

package/dist/chunks/{chunk-3CUI2HDG.js → chunk-5E2G77WW.js}

@@ -1,10 +1,27 @@
 // Force strict mode and setup for ESM
 "use strict";
+const __papertOriginalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = function patchedEmitWarning(warning, ...args) {
+  if (!process.env.PAPERT_SHOW_NODE_DEPRECATIONS) {
+    const warningCode =
+      (warning && typeof warning === 'object' && 'code' in warning && warning.code) ||
+      (args.length > 1 && typeof args[1] === 'string' && args[1]) ||
+      (args.length > 0 &&
+        args[0] &&
+        typeof args[0] === 'object' &&
+        'code' in args[0] &&
+        args[0].code);
+    if (warningCode === 'DEP0040' || warningCode === 'DEP0169') {
+      return;
+    }
+  }
+  return __papertOriginalEmitWarning(warning, ...args);
+};
 import {
   __commonJS,
   __name,
   init_esbuild_shims
-} from "./chunk-4HTLIVVR.js";
+} from "./chunk-NCFEMX7E.js";
 
 // node_modules/react-devtools-core/dist/backend.js
 var require_backend = __commonJS({