@punch-bot/cli 0.85.1 → 1.3.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/CHANGELOG.md +609 -3
- package/README.md +82 -174
- package/dist/bun/cli.d.ts.map +1 -1
- package/dist/bun/restore-sandbox-env.d.ts.map +1 -1
- package/dist/bun/restore-sandbox-env.js.map +1 -1
- package/dist/bun/runtime-setup.d.ts.map +1 -1
- package/dist/bun/runtime-setup.js +4 -1
- package/dist/bun/runtime-setup.js.map +1 -1
- package/dist/bun/sandbox-env-setup.d.ts.map +1 -1
- package/dist/bundle/chunks/anthropic-messages-BUUFZMRE.js +6 -0
- package/dist/bundle/chunks/anthropic.js +2 -2
- package/dist/bundle/chunks/azure-openai-responses-WZ4GZHD2.js +2 -0
- package/dist/bundle/chunks/bedrock-converse-stream.js +10 -2
- package/dist/bundle/chunks/chunk-22CYIUS4.js +2 -0
- package/dist/bundle/chunks/chunk-2M76JOVH.js +8 -0
- package/dist/bundle/chunks/chunk-6C5VKHGV.js +50 -0
- package/dist/bundle/chunks/chunk-6WNF4BLC.js +2 -0
- package/dist/bundle/chunks/chunk-6YKFJ7FQ.js +1188 -0
- package/dist/bundle/chunks/chunk-BYHXHV4K.js +11 -0
- package/dist/bundle/chunks/chunk-F5ZABL6Z.js +20 -0
- package/dist/bundle/chunks/chunk-HACVPRBJ.js +11 -0
- package/dist/bundle/chunks/chunk-ITZNWD4K.js +2 -0
- package/dist/bundle/chunks/chunk-J7I2NFJ7.js +82 -0
- package/dist/bundle/chunks/chunk-LPXNMA2W.js +2 -0
- package/dist/bundle/chunks/chunk-OO6DJ3CL.js +31 -0
- package/dist/bundle/chunks/chunk-OWCYH5W2.js +2 -0
- package/dist/bundle/chunks/chunk-PMRZO46Y.js +2 -0
- package/dist/bundle/chunks/{chunk-TRDNDS6A.js → chunk-PYGXRV27.js} +5 -2
- package/dist/bundle/chunks/chunk-RDZVAGPR.js +2 -0
- package/dist/bundle/chunks/{chunk-XDUWOHPL.js → chunk-S3GGRYIO.js} +2 -2
- package/dist/bundle/chunks/chunk-UTB4DTYQ.js +2 -0
- package/dist/bundle/chunks/chunk-WUIPA42N.js +14 -0
- package/dist/bundle/chunks/chunk-XIX7LUWI.js +2 -0
- package/dist/bundle/chunks/{chunk-3DNTDXPG.js → chunk-YGGF2ZM6.js} +3 -3
- package/dist/bundle/chunks/chunk-YWHGLBPB.js +2 -0
- package/dist/bundle/chunks/chunk-ZBURYEWF.js +2 -0
- package/dist/bundle/chunks/cli-QAQLORRY.js +51 -0
- package/dist/bundle/chunks/cloudflare-workers-ai-system-one-UTBL2KOF.js +2 -0
- package/dist/bundle/chunks/codemode-worker.js +478 -0
- package/dist/bundle/chunks/execute-2Z6BN5R3.js +499 -0
- package/dist/bundle/chunks/github-copilot.js +1 -1
- package/dist/bundle/chunks/google-generative-ai-S2KXX5PQ.js +2 -0
- package/dist/bundle/chunks/google-vertex-LQOUTFJN.js +2 -0
- package/dist/bundle/chunks/image-resize-worker.js +1 -1
- package/dist/bundle/chunks/jiti-loader-C3NU2SDH.js +21 -0
- package/dist/bundle/chunks/jiti-static-loader-E6ANQD5T.js +2 -0
- package/dist/bundle/chunks/{lib-HGQMNYVT.js → lib-TEDK3E5I.js} +2 -2
- package/dist/bundle/chunks/llama-cpp-classify-FYN623RH.js +22 -0
- package/dist/bundle/chunks/meta.js +2 -0
- package/dist/bundle/chunks/mistral-conversations-VNJYBSRF.js +5 -0
- package/dist/bundle/chunks/node-N5BSDOA5.js +16 -0
- package/dist/bundle/chunks/{node-4PXJTSWH.js → node-TWVVAGPO.js} +1 -1
- package/dist/bundle/chunks/openai-chatgpt.js +75 -0
- package/dist/bundle/chunks/openai-codex-responses-E6BLZPYJ.js +10 -0
- package/dist/bundle/chunks/openai-codex.js +2 -2
- package/dist/bundle/chunks/openai-completions-LUDIAWSG.js +7 -0
- package/dist/bundle/chunks/openai-decisions-WVPMQ4JD.js +5 -0
- package/dist/bundle/chunks/openai-responses-IOCBEIVC.js +3 -0
- package/dist/bundle/chunks/{openrouter-images-N4XVVFSD.js → openrouter-images-YU24TD7D.js} +1 -1
- package/dist/bundle/chunks/openrouter.js +2 -2
- package/dist/bundle/chunks/{pi-messages-ZRYGTSON.js → pi-messages-V27DSLVC.js} +2 -2
- package/dist/bundle/chunks/radius.js +2 -2
- package/dist/bundle/chunks/runtime-R6O72Q4R.js +2 -0
- package/dist/bundle/chunks/typesafe-system-one-ZSK3RN4B.js +2 -0
- package/dist/bundle/chunks/virtual-modules-GZVZPCK3.js +2 -0
- package/dist/bundle/cli-runtime.js +3 -0
- package/dist/bundle/cli.js +4 -2
- package/dist/bundle/index.js +1 -1
- package/dist/bundle/rpc-entry.js +1 -1
- package/dist/cli/args.d.ts +1 -2
- package/dist/cli/args.d.ts.map +1 -1
- package/dist/cli/args.js +73 -53
- package/dist/cli/args.js.map +1 -1
- package/dist/cli/auth-check.d.ts.map +1 -1
- package/dist/cli/auth-check.js.map +1 -1
- package/dist/cli/auth-command.d.ts.map +1 -1
- package/dist/cli/auth-command.js.map +1 -1
- package/dist/cli/credential-print.d.ts.map +1 -1
- package/dist/cli/credential-print.js +4 -4
- package/dist/cli/credential-print.js.map +1 -1
- package/dist/cli/experimental/transport-address.d.ts +21 -0
- package/dist/cli/experimental/transport-address.d.ts.map +1 -0
- package/dist/cli/experimental/transport-address.js +89 -0
- package/dist/cli/experimental/transport-address.js.map +1 -0
- package/dist/cli/file-processor.d.ts +1 -1
- package/dist/cli/file-processor.d.ts.map +1 -1
- package/dist/cli/file-processor.js.map +1 -1
- package/dist/cli/initial-message.d.ts +1 -1
- package/dist/cli/initial-message.d.ts.map +1 -1
- package/dist/cli/initial-message.js.map +1 -1
- package/dist/cli/list-models.d.ts.map +1 -1
- package/dist/cli/list-models.js +1 -1
- package/dist/cli/list-models.js.map +1 -1
- package/dist/cli/project-trust.d.ts.map +1 -1
- package/dist/cli/project-trust.js +5 -35
- package/dist/cli/project-trust.js.map +1 -1
- package/dist/cli/setup.d.ts.map +1 -1
- package/dist/cli/setup.js.map +1 -1
- package/dist/cli.d.ts.map +1 -1
- package/dist/config.d.ts +30 -11
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +72 -21
- package/dist/config.js.map +1 -1
- package/dist/core/agent-session-runtime.d.ts +4 -3
- package/dist/core/agent-session-runtime.d.ts.map +1 -1
- package/dist/core/agent-session-runtime.js +37 -27
- package/dist/core/agent-session-runtime.js.map +1 -1
- package/dist/core/agent-session-services.d.ts.map +1 -1
- package/dist/core/agent-session-services.js +13 -0
- package/dist/core/agent-session-services.js.map +1 -1
- package/dist/core/agent-session.d.ts +270 -22
- package/dist/core/agent-session.d.ts.map +1 -1
- package/dist/core/agent-session.js +1174 -410
- package/dist/core/agent-session.js.map +1 -1
- package/dist/core/auth-guidance.d.ts.map +1 -1
- package/dist/core/auth-guidance.js.map +1 -1
- package/dist/core/auth-storage.d.ts.map +1 -1
- package/dist/core/auth-storage.js +20 -13
- package/dist/core/auth-storage.js.map +1 -1
- package/dist/core/bash-executor.d.ts.map +1 -1
- package/dist/core/bash-executor.js +42 -52
- package/dist/core/bash-executor.js.map +1 -1
- package/dist/core/bug-report-upload.d.ts +12 -0
- package/dist/core/bug-report-upload.d.ts.map +1 -0
- package/dist/core/bug-report-upload.js +22 -0
- package/dist/core/bug-report-upload.js.map +1 -0
- package/dist/core/bug-report.d.ts +184 -0
- package/dist/core/bug-report.d.ts.map +1 -0
- package/dist/core/bug-report.js +292 -0
- package/dist/core/bug-report.js.map +1 -0
- package/dist/core/cache-stats.d.ts.map +1 -1
- package/dist/core/cache-stats.js +12 -1
- package/dist/core/cache-stats.js.map +1 -1
- package/dist/core/cache-warmer.d.ts +103 -0
- package/dist/core/cache-warmer.d.ts.map +1 -0
- package/dist/core/cache-warmer.js +356 -0
- package/dist/core/cache-warmer.js.map +1 -0
- package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
- package/dist/core/compaction/branch-summarization.js +2 -2
- package/dist/core/compaction/branch-summarization.js.map +1 -1
- package/dist/core/compaction/compaction.d.ts +5 -3
- package/dist/core/compaction/compaction.d.ts.map +1 -1
- package/dist/core/compaction/compaction.js +164 -88
- package/dist/core/compaction/compaction.js.map +1 -1
- package/dist/core/compaction/index.d.ts.map +1 -1
- package/dist/core/compaction/utils.d.ts +8 -1
- package/dist/core/compaction/utils.d.ts.map +1 -1
- package/dist/core/compaction/utils.js +32 -26
- package/dist/core/compaction/utils.js.map +1 -1
- package/dist/core/crash-log.d.ts +27 -0
- package/dist/core/crash-log.d.ts.map +1 -0
- package/dist/core/crash-log.js +140 -0
- package/dist/core/crash-log.js.map +1 -0
- package/dist/core/defaults.d.ts.map +1 -1
- package/dist/core/delivery.d.ts.map +1 -1
- package/dist/core/delivery.js.map +1 -1
- package/dist/core/diagnostics.d.ts.map +1 -1
- package/dist/core/event-bus.d.ts.map +1 -1
- package/dist/core/event-bus.js.map +1 -1
- package/dist/core/exec.d.ts.map +1 -1
- package/dist/core/exec.js.map +1 -1
- package/dist/core/experimental.d.ts.map +1 -1
- package/dist/core/experimental.js.map +1 -1
- package/dist/core/export-html/ansi-to-html.d.ts.map +1 -1
- package/dist/core/export-html/ansi-to-html.js.map +1 -1
- package/dist/core/export-html/index.d.ts.map +1 -1
- package/dist/core/export-html/index.js +1 -1
- package/dist/core/export-html/index.js.map +1 -1
- package/dist/core/export-html/template.css +10 -0
- package/dist/core/export-html/template.js +93 -34
- package/dist/core/export-html/tool-renderer.d.ts +5 -11
- package/dist/core/export-html/tool-renderer.d.ts.map +1 -1
- package/dist/core/export-html/tool-renderer.js +8 -99
- package/dist/core/export-html/tool-renderer.js.map +1 -1
- package/dist/core/extensions/index.d.ts +1 -1
- package/dist/core/extensions/index.d.ts.map +1 -1
- package/dist/core/extensions/index.js.map +1 -1
- package/dist/core/extensions/jiti-loader.d.ts +2 -0
- package/dist/core/extensions/jiti-loader.d.ts.map +1 -0
- package/dist/core/extensions/jiti-loader.js +4 -0
- package/dist/core/extensions/jiti-loader.js.map +1 -0
- package/dist/core/extensions/jiti-static-loader.d.ts +2 -0
- package/dist/core/extensions/jiti-static-loader.d.ts.map +1 -0
- package/dist/core/extensions/jiti-static-loader.js +4 -0
- package/dist/core/extensions/jiti-static-loader.js.map +1 -0
- package/dist/core/extensions/loader.d.ts.map +1 -1
- package/dist/core/extensions/loader.js +102 -74
- package/dist/core/extensions/loader.js.map +1 -1
- package/dist/core/extensions/runner.d.ts +44 -14
- package/dist/core/extensions/runner.d.ts.map +1 -1
- package/dist/core/extensions/runner.js +297 -169
- package/dist/core/extensions/runner.js.map +1 -1
- package/dist/core/extensions/types.d.ts +482 -238
- package/dist/core/extensions/types.d.ts.map +1 -1
- package/dist/core/extensions/types.js.map +1 -1
- package/dist/core/extensions/virtual-modules.d.ts +3 -0
- package/dist/core/extensions/virtual-modules.d.ts.map +1 -0
- package/dist/core/extensions/virtual-modules.js +35 -0
- package/dist/core/extensions/virtual-modules.js.map +1 -0
- package/dist/core/extensions/wrapper.d.ts +2 -2
- package/dist/core/extensions/wrapper.d.ts.map +1 -1
- package/dist/core/extensions/wrapper.js +3 -22
- package/dist/core/extensions/wrapper.js.map +1 -1
- package/dist/core/footer-data-provider.d.ts.map +1 -1
- package/dist/core/footer-data-provider.js.map +1 -1
- package/dist/core/http-dispatcher.d.ts +13 -0
- package/dist/core/http-dispatcher.d.ts.map +1 -1
- package/dist/core/http-dispatcher.js +13 -4
- package/dist/core/http-dispatcher.js.map +1 -1
- package/dist/core/index.d.ts +2 -1
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js.map +1 -1
- package/dist/core/mcp-servers.d.ts +139 -0
- package/dist/core/mcp-servers.d.ts.map +1 -0
- package/dist/core/mcp-servers.js +232 -0
- package/dist/core/mcp-servers.js.map +1 -0
- package/dist/core/messages.d.ts.map +1 -1
- package/dist/core/messages.js +1 -0
- package/dist/core/messages.js.map +1 -1
- package/dist/{modes/interactive → core}/model-catalog-refresh.d.ts +2 -2
- package/dist/core/model-catalog-refresh.d.ts.map +1 -0
- package/dist/{modes/interactive → core}/model-catalog-refresh.js +2 -2
- package/dist/core/model-catalog-refresh.js.map +1 -0
- package/dist/core/model-config.d.ts +886 -80
- package/dist/core/model-config.d.ts.map +1 -1
- package/dist/core/model-config.js +33 -148
- package/dist/core/model-config.js.map +1 -1
- package/dist/core/model-registry.d.ts +15 -1
- package/dist/core/model-registry.d.ts.map +1 -1
- package/dist/core/model-registry.js +29 -0
- package/dist/core/model-registry.js.map +1 -1
- package/dist/core/model-resolver.d.ts +61 -46
- package/dist/core/model-resolver.d.ts.map +1 -1
- package/dist/core/model-resolver.js +338 -363
- package/dist/core/model-resolver.js.map +1 -1
- package/dist/core/model-runtime.d.ts +51 -3
- package/dist/core/model-runtime.d.ts.map +1 -1
- package/dist/core/model-runtime.js +211 -44
- package/dist/core/model-runtime.js.map +1 -1
- package/dist/core/model-suffix-variants.d.ts +14 -0
- package/dist/core/model-suffix-variants.d.ts.map +1 -0
- package/dist/core/model-suffix-variants.js +27 -0
- package/dist/core/model-suffix-variants.js.map +1 -0
- package/dist/core/models-store.d.ts.map +1 -1
- package/dist/core/models-store.js.map +1 -1
- package/dist/core/nested-tool-calls.d.ts +103 -0
- package/dist/core/nested-tool-calls.d.ts.map +1 -0
- package/dist/core/nested-tool-calls.js +179 -0
- package/dist/core/nested-tool-calls.js.map +1 -0
- package/dist/core/output-guard.d.ts.map +1 -1
- package/dist/core/output-guard.js.map +1 -1
- package/dist/core/package-manager.d.ts +4 -0
- package/dist/core/package-manager.d.ts.map +1 -1
- package/dist/core/package-manager.js +62 -15
- package/dist/core/package-manager.js.map +1 -1
- package/dist/core/pi-manifest.d.ts.map +1 -1
- package/dist/core/pi-manifest.js.map +1 -1
- package/dist/core/project-trust.d.ts.map +1 -1
- package/dist/core/project-trust.js +2 -1
- package/dist/core/project-trust.js.map +1 -1
- package/dist/core/prompt-templates.d.ts +6 -1
- package/dist/core/prompt-templates.d.ts.map +1 -1
- package/dist/core/prompt-templates.js +68 -37
- package/dist/core/prompt-templates.js.map +1 -1
- package/dist/core/provider-attribution.d.ts.map +1 -1
- package/dist/core/provider-attribution.js.map +1 -1
- package/dist/core/provider-composer.d.ts +42 -20
- package/dist/core/provider-composer.d.ts.map +1 -1
- package/dist/core/provider-composer.js +126 -40
- package/dist/core/provider-composer.js.map +1 -1
- package/dist/core/radius.d.ts +5 -0
- package/dist/core/radius.d.ts.map +1 -1
- package/dist/core/radius.js +8 -0
- package/dist/core/radius.js.map +1 -1
- package/dist/core/remote-catalog-provider.d.ts +19 -1
- package/dist/core/remote-catalog-provider.d.ts.map +1 -1
- package/dist/core/remote-catalog-provider.js +102 -34
- package/dist/core/remote-catalog-provider.js.map +1 -1
- package/dist/core/resolve-config-value.d.ts.map +1 -1
- package/dist/core/resolve-config-value.js.map +1 -1
- package/dist/core/resource-loader.d.ts +11 -2
- package/dist/core/resource-loader.d.ts.map +1 -1
- package/dist/core/resource-loader.js +170 -42
- package/dist/core/resource-loader.js.map +1 -1
- package/dist/core/runtime-credentials.d.ts.map +1 -1
- package/dist/core/runtime-credentials.js.map +1 -1
- package/dist/core/sdk.d.ts +14 -5
- package/dist/core/sdk.d.ts.map +1 -1
- package/dist/core/sdk.js +108 -52
- package/dist/core/sdk.js.map +1 -1
- package/dist/core/session-cwd.d.ts.map +1 -1
- package/dist/core/session-cwd.js.map +1 -1
- package/dist/core/session-export.d.ts +6 -2
- package/dist/core/session-export.d.ts.map +1 -1
- package/dist/core/session-export.js +14 -13
- package/dist/core/session-export.js.map +1 -1
- package/dist/core/session-manager.d.ts +72 -13
- package/dist/core/session-manager.d.ts.map +1 -1
- package/dist/core/session-manager.js +277 -124
- package/dist/core/session-manager.js.map +1 -1
- package/dist/core/settings-defaults.d.ts +65 -0
- package/dist/core/settings-defaults.d.ts.map +1 -0
- package/dist/core/settings-defaults.js +66 -0
- package/dist/core/settings-defaults.js.map +1 -0
- package/dist/core/settings-diagnostics.d.ts.map +1 -1
- package/dist/core/settings-diagnostics.js.map +1 -1
- package/dist/core/settings-manager.d.ts +41 -126
- package/dist/core/settings-manager.d.ts.map +1 -1
- package/dist/core/settings-manager.js +165 -52
- package/dist/core/settings-manager.js.map +1 -1
- package/dist/core/settings-schema.d.ts +224 -0
- package/dist/core/settings-schema.d.ts.map +1 -0
- package/dist/core/settings-schema.js +285 -0
- package/dist/core/settings-schema.js.map +1 -0
- package/dist/core/skills.d.ts +4 -1
- package/dist/core/skills.d.ts.map +1 -1
- package/dist/core/skills.js +6 -1
- package/dist/core/skills.js.map +1 -1
- package/dist/core/slash-commands.d.ts.map +1 -1
- package/dist/core/slash-commands.js +3 -2
- package/dist/core/slash-commands.js.map +1 -1
- package/dist/core/source-info.d.ts +8 -0
- package/dist/core/source-info.d.ts.map +1 -1
- package/dist/core/source-info.js +16 -0
- package/dist/core/source-info.js.map +1 -1
- package/dist/core/system-prompt.d.ts +55 -6
- package/dist/core/system-prompt.d.ts.map +1 -1
- package/dist/core/system-prompt.js +128 -93
- package/dist/core/system-prompt.js.map +1 -1
- package/dist/core/telemetry.d.ts +2 -0
- package/dist/core/telemetry.d.ts.map +1 -1
- package/dist/core/telemetry.js +45 -0
- package/dist/core/telemetry.js.map +1 -1
- package/dist/core/theme/dark.json +78 -0
- package/dist/core/theme/light.json +78 -0
- package/dist/core/theme/system-theme.d.ts +54 -0
- package/dist/core/theme/system-theme.d.ts.map +1 -0
- package/dist/core/theme/system-theme.js +547 -0
- package/dist/core/theme/system-theme.js.map +1 -0
- package/dist/core/theme/theme-schema.d.ts +28 -0
- package/dist/core/theme/theme-schema.d.ts.map +1 -0
- package/dist/core/theme/theme-schema.js +105 -0
- package/dist/core/theme/theme-schema.js.map +1 -0
- package/dist/core/theme/theme-tokens.d.ts +257 -0
- package/dist/core/theme/theme-tokens.d.ts.map +1 -0
- package/dist/core/theme/theme-tokens.js +94 -0
- package/dist/core/theme/theme-tokens.js.map +1 -0
- package/dist/core/theme/theme.d.ts +162 -0
- package/dist/core/theme/theme.d.ts.map +1 -0
- package/dist/{modes/interactive → core}/theme/theme.js +265 -402
- package/dist/core/theme/theme.js.map +1 -0
- package/dist/core/timings.d.ts.map +1 -1
- package/dist/core/timings.js.map +1 -1
- package/dist/core/tools/bash.d.ts +14 -1
- package/dist/core/tools/bash.d.ts.map +1 -1
- package/dist/core/tools/bash.js +43 -6
- package/dist/core/tools/bash.js.map +1 -1
- package/dist/core/tools/edit-diff.d.ts.map +1 -1
- package/dist/core/tools/edit-diff.js.map +1 -1
- package/dist/core/tools/edit.d.ts +1 -2
- package/dist/core/tools/edit.d.ts.map +1 -1
- package/dist/core/tools/edit.js +0 -3
- package/dist/core/tools/edit.js.map +1 -1
- package/dist/core/tools/file-mutation-queue.d.ts.map +1 -1
- package/dist/core/tools/file-mutation-queue.js.map +1 -1
- package/dist/core/tools/find.d.ts.map +1 -1
- package/dist/core/tools/find.js +0 -2
- package/dist/core/tools/find.js.map +1 -1
- package/dist/core/tools/grep.d.ts.map +1 -1
- package/dist/core/tools/grep.js +0 -2
- package/dist/core/tools/grep.js.map +1 -1
- package/dist/core/tools/index.d.ts.map +1 -1
- package/dist/core/tools/index.js.map +1 -1
- package/dist/core/tools/ls.d.ts.map +1 -1
- package/dist/core/tools/ls.js +0 -2
- package/dist/core/tools/ls.js.map +1 -1
- package/dist/core/tools/output-accumulator.d.ts +11 -0
- package/dist/core/tools/output-accumulator.d.ts.map +1 -1
- package/dist/core/tools/output-accumulator.js +40 -10
- package/dist/core/tools/output-accumulator.js.map +1 -1
- package/dist/core/tools/path-utils.d.ts.map +1 -1
- package/dist/core/tools/path-utils.js.map +1 -1
- package/dist/core/tools/powershell.d.ts.map +1 -1
- package/dist/core/tools/powershell.js.map +1 -1
- package/dist/core/tools/read.d.ts +17 -1
- package/dist/core/tools/read.d.ts.map +1 -1
- package/dist/core/tools/read.js +23 -4
- package/dist/core/tools/read.js.map +1 -1
- package/dist/core/tools/tool-definition-wrapper.d.ts +5 -3
- package/dist/core/tools/tool-definition-wrapper.d.ts.map +1 -1
- package/dist/core/tools/tool-definition-wrapper.js +3 -1
- package/dist/core/tools/tool-definition-wrapper.js.map +1 -1
- package/dist/core/tools/truncate.d.ts +14 -0
- package/dist/core/tools/truncate.d.ts.map +1 -1
- package/dist/core/tools/truncate.js +29 -0
- package/dist/core/tools/truncate.js.map +1 -1
- package/dist/core/tools/write.d.ts.map +1 -1
- package/dist/core/tools/write.js +0 -2
- package/dist/core/tools/write.js.map +1 -1
- package/dist/core/trust-manager.d.ts.map +1 -1
- package/dist/core/trust-manager.js +1 -0
- package/dist/core/trust-manager.js.map +1 -1
- package/dist/core/usage-totals.d.ts +3 -1
- package/dist/core/usage-totals.d.ts.map +1 -1
- package/dist/core/usage-totals.js +28 -1
- package/dist/core/usage-totals.js.map +1 -1
- package/dist/core/virtual-models.d.ts +117 -0
- package/dist/core/virtual-models.d.ts.map +1 -0
- package/dist/core/virtual-models.js +124 -0
- package/dist/core/virtual-models.js.map +1 -0
- package/dist/extensions/browser/index.d.ts.map +1 -1
- package/dist/extensions/browser/index.js.map +1 -1
- package/dist/extensions/codemode/execute.d.ts +16 -0
- package/dist/extensions/codemode/execute.d.ts.map +1 -0
- package/dist/extensions/codemode/execute.js +665 -0
- package/dist/extensions/codemode/execute.js.map +1 -0
- package/dist/extensions/codemode/execute.lazy.d.ts +3 -0
- package/dist/extensions/codemode/execute.lazy.d.ts.map +1 -0
- package/dist/extensions/codemode/execute.lazy.js +3 -0
- package/dist/extensions/codemode/execute.lazy.js.map +1 -0
- package/dist/extensions/codemode/index.d.ts +21 -0
- package/dist/extensions/codemode/index.d.ts.map +1 -0
- package/dist/extensions/codemode/index.js +33 -0
- package/dist/extensions/codemode/index.js.map +1 -0
- package/dist/extensions/codemode/tool.d.ts +124 -0
- package/dist/extensions/codemode/tool.d.ts.map +1 -0
- package/dist/extensions/codemode/tool.js +286 -0
- package/dist/extensions/codemode/tool.js.map +1 -0
- package/dist/extensions/codemode/worker.d.ts +7 -0
- package/dist/extensions/codemode/worker.d.ts.map +1 -0
- package/dist/extensions/codemode/worker.js +7 -0
- package/dist/extensions/codemode/worker.js.map +1 -0
- package/dist/extensions/context-pruning/compress_context.d.ts.map +1 -1
- package/dist/extensions/context-pruning/compress_context.js +1 -3
- package/dist/extensions/context-pruning/compress_context.js.map +1 -1
- package/dist/extensions/context-pruning/context-pruning-state.d.ts.map +1 -1
- package/dist/extensions/context-pruning/context-pruning-state.js.map +1 -1
- package/dist/extensions/index.d.ts.map +1 -1
- package/dist/extensions/index.js +6 -2
- package/dist/extensions/index.js.map +1 -1
- package/dist/extensions/llama/client.d.ts +2 -0
- package/dist/extensions/llama/client.d.ts.map +1 -1
- package/dist/extensions/llama/client.js +7 -3
- package/dist/extensions/llama/client.js.map +1 -1
- package/dist/extensions/llama/huggingface.d.ts.map +1 -1
- package/dist/extensions/llama/huggingface.js.map +1 -1
- package/dist/extensions/llama/index.d.ts.map +1 -1
- package/dist/extensions/llama/index.js +0 -4
- package/dist/extensions/llama/index.js.map +1 -1
- package/dist/extensions/llama/provider.d.ts +1 -1
- package/dist/extensions/llama/provider.d.ts.map +1 -1
- package/dist/extensions/llama/provider.js +103 -13
- package/dist/extensions/llama/provider.js.map +1 -1
- package/dist/extensions/llama/ui.d.ts +3 -2
- package/dist/extensions/llama/ui.d.ts.map +1 -1
- package/dist/extensions/llama/ui.js +106 -364
- package/dist/extensions/llama/ui.js.map +1 -1
- package/dist/extensions/mcp/cli.d.ts +21 -0
- package/dist/extensions/mcp/cli.d.ts.map +1 -0
- package/dist/extensions/mcp/cli.js +494 -0
- package/dist/extensions/mcp/cli.js.map +1 -0
- package/dist/extensions/mcp/cli.lazy.d.ts +3 -0
- package/dist/extensions/mcp/cli.lazy.d.ts.map +1 -0
- package/dist/extensions/mcp/cli.lazy.js +3 -0
- package/dist/extensions/mcp/cli.lazy.js.map +1 -0
- package/dist/extensions/mcp/config.d.ts +84 -0
- package/dist/extensions/mcp/config.d.ts.map +1 -0
- package/dist/extensions/mcp/config.js +196 -0
- package/dist/extensions/mcp/config.js.map +1 -0
- package/dist/extensions/mcp/index.d.ts +71 -2
- package/dist/extensions/mcp/index.d.ts.map +1 -1
- package/dist/extensions/mcp/index.js +839 -131
- package/dist/extensions/mcp/index.js.map +1 -1
- package/dist/extensions/mcp/log.d.ts +16 -0
- package/dist/extensions/mcp/log.d.ts.map +1 -0
- package/dist/extensions/mcp/log.js +66 -0
- package/dist/extensions/mcp/log.js.map +1 -0
- package/dist/extensions/mcp/oauth.d.ts +102 -0
- package/dist/extensions/mcp/oauth.d.ts.map +1 -0
- package/dist/extensions/mcp/oauth.js +428 -0
- package/dist/extensions/mcp/oauth.js.map +1 -0
- package/dist/extensions/mcp/resources.d.ts +36 -0
- package/dist/extensions/mcp/resources.d.ts.map +1 -0
- package/dist/extensions/mcp/resources.js +261 -0
- package/dist/extensions/mcp/resources.js.map +1 -0
- package/dist/extensions/mcp/runtime.d.ts +98 -0
- package/dist/extensions/mcp/runtime.d.ts.map +1 -0
- package/dist/extensions/mcp/runtime.js +378 -0
- package/dist/extensions/mcp/runtime.js.map +1 -0
- package/dist/extensions/mcp/runtime.lazy.d.ts +3 -0
- package/dist/extensions/mcp/runtime.lazy.d.ts.map +1 -0
- package/dist/extensions/mcp/runtime.lazy.js +3 -0
- package/dist/extensions/mcp/runtime.lazy.js.map +1 -0
- package/dist/extensions/mcp/tools.d.ts +84 -0
- package/dist/extensions/mcp/tools.d.ts.map +1 -0
- package/dist/extensions/mcp/tools.js +263 -0
- package/dist/extensions/mcp/tools.js.map +1 -0
- package/dist/extensions/punch/a2a-listen.d.ts +9 -0
- package/dist/extensions/punch/a2a-listen.d.ts.map +1 -0
- package/dist/extensions/punch/a2a-listen.js +88 -0
- package/dist/extensions/punch/a2a-listen.js.map +1 -0
- package/dist/extensions/punch/a2a.d.ts +12 -0
- package/dist/extensions/punch/a2a.d.ts.map +1 -0
- package/dist/extensions/punch/a2a.js +106 -0
- package/dist/extensions/punch/a2a.js.map +1 -0
- package/dist/extensions/punch/auth.d.ts +2 -1
- package/dist/extensions/punch/auth.d.ts.map +1 -1
- package/dist/extensions/punch/auth.js +5 -1
- package/dist/extensions/punch/auth.js.map +1 -1
- package/dist/extensions/punch/collabs.d.ts.map +1 -1
- package/dist/extensions/punch/collabs.js.map +1 -1
- package/dist/extensions/punch/index.d.ts.map +1 -1
- package/dist/extensions/punch/index.js +11 -15
- package/dist/extensions/punch/index.js.map +1 -1
- package/dist/extensions/punch/routines.d.ts +1 -3
- package/dist/extensions/punch/routines.d.ts.map +1 -1
- package/dist/extensions/punch/routines.js +1 -121
- package/dist/extensions/punch/routines.js.map +1 -1
- package/dist/extensions/punch/server.d.ts +3 -0
- package/dist/extensions/punch/server.d.ts.map +1 -1
- package/dist/extensions/punch/server.js +41 -3
- package/dist/extensions/punch/server.js.map +1 -1
- package/dist/extensions/punch/timezone.d.ts.map +1 -1
- package/dist/extensions/punch/timezone.js.map +1 -1
- package/dist/extensions/punch/todo-store.d.ts +15 -0
- package/dist/extensions/punch/todo-store.d.ts.map +1 -0
- package/dist/extensions/punch/todo-store.js +208 -0
- package/dist/extensions/punch/todo-store.js.map +1 -0
- package/dist/extensions/punch/todos.d.ts +7 -3
- package/dist/extensions/punch/todos.d.ts.map +1 -1
- package/dist/extensions/punch/todos.js +40 -17
- package/dist/extensions/punch/todos.js.map +1 -1
- package/dist/extensions/report-progress/index.d.ts.map +1 -1
- package/dist/extensions/report-progress/index.js.map +1 -1
- package/dist/extensions/subagent/agents.d.ts.map +1 -1
- package/dist/extensions/subagent/agents.js.map +1 -1
- package/dist/extensions/subagent/index.d.ts.map +1 -1
- package/dist/extensions/subagent/index.js +0 -372
- package/dist/extensions/subagent/index.js.map +1 -1
- package/dist/extensions/tool-search/index.d.ts +12 -0
- package/dist/extensions/tool-search/index.d.ts.map +1 -0
- package/dist/extensions/tool-search/index.js +15 -0
- package/dist/extensions/tool-search/index.js.map +1 -0
- package/dist/extensions/tool-search/tool.d.ts +71 -0
- package/dist/extensions/tool-search/tool.d.ts.map +1 -0
- package/dist/extensions/tool-search/tool.js +187 -0
- package/dist/extensions/tool-search/tool.js.map +1 -0
- package/dist/extensions/webfetch/index.d.ts.map +1 -1
- package/dist/extensions/webfetch/index.js.map +1 -1
- package/dist/extensions/websearch/index.d.ts.map +1 -1
- package/dist/extensions/websearch/index.js.map +1 -1
- package/dist/index.d.ts +13 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +9 -6
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +140 -173
- package/dist/main.js.map +1 -1
- package/dist/migrations.d.ts.map +1 -1
- package/dist/migrations.js +0 -20
- package/dist/migrations.js.map +1 -1
- package/dist/modes/index.d.ts +0 -1
- package/dist/modes/index.d.ts.map +1 -1
- package/dist/modes/index.js +0 -1
- package/dist/modes/index.js.map +1 -1
- package/dist/modes/json-event.d.ts.map +1 -1
- package/dist/modes/json-event.js.map +1 -1
- package/dist/modes/print-mode.d.ts.map +1 -1
- package/dist/modes/print-mode.js +4 -0
- package/dist/modes/print-mode.js.map +1 -1
- package/dist/modes/rpc/jsonl.d.ts.map +1 -1
- package/dist/modes/rpc/jsonl.js.map +1 -1
- package/dist/modes/rpc/rpc-client.d.ts +10 -6
- package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-client.js +19 -8
- package/dist/modes/rpc/rpc-client.js.map +1 -1
- package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-mode.js +30 -48
- package/dist/modes/rpc/rpc-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-types.d.ts +21 -1
- package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-types.js.map +1 -1
- package/dist/package-manager-cli.d.ts.map +1 -1
- package/dist/package-manager-cli.js +43 -43
- package/dist/package-manager-cli.js.map +1 -1
- package/dist/rpc-entry.d.ts.map +1 -1
- package/dist/rpc-entry.js.map +1 -1
- package/dist/server/a2a/harness-runner.d.ts.map +1 -1
- package/dist/server/a2a/harness-runner.js.map +1 -1
- package/dist/server/a2a/run-server.d.ts.map +1 -1
- package/dist/server/a2a/run-server.js.map +1 -1
- package/dist/utils/abort.d.ts.map +1 -1
- package/dist/utils/abort.js.map +1 -1
- package/dist/utils/ansi.d.ts +8 -0
- package/dist/utils/ansi.d.ts.map +1 -1
- package/dist/utils/ansi.js +30 -11
- package/dist/utils/ansi.js.map +1 -1
- package/dist/utils/changelog.d.ts.map +1 -1
- package/dist/utils/changelog.js +5 -2
- package/dist/utils/changelog.js.map +1 -1
- package/dist/utils/child-process.d.ts.map +1 -1
- package/dist/utils/child-process.js.map +1 -1
- package/dist/utils/clipboard-command.d.ts.map +1 -1
- package/dist/utils/clipboard-command.js.map +1 -1
- package/dist/utils/clipboard-image.d.ts.map +1 -1
- package/dist/utils/clipboard-image.js +15 -41
- package/dist/utils/clipboard-image.js.map +1 -1
- package/dist/utils/clipboard.d.ts.map +1 -1
- package/dist/utils/clipboard.js +96 -38
- package/dist/utils/clipboard.js.map +1 -1
- package/dist/utils/colors.d.ts +73 -0
- package/dist/utils/colors.d.ts.map +1 -0
- package/dist/utils/colors.js +273 -0
- package/dist/utils/colors.js.map +1 -0
- package/dist/utils/deprecation.d.ts.map +1 -1
- package/dist/utils/deprecation.js.map +1 -1
- package/dist/utils/exif-orientation.d.ts.map +1 -1
- package/dist/utils/exif-orientation.js.map +1 -1
- package/dist/utils/frontmatter.d.ts.map +1 -1
- package/dist/utils/frontmatter.js.map +1 -1
- package/dist/utils/fs-watch.d.ts.map +1 -1
- package/dist/utils/fs-watch.js.map +1 -1
- package/dist/utils/fuzzy.d.ts +16 -0
- package/dist/utils/fuzzy.d.ts.map +1 -0
- package/dist/utils/fuzzy.js +111 -0
- package/dist/utils/fuzzy.js.map +1 -0
- package/dist/utils/git.d.ts.map +1 -1
- package/dist/utils/git.js.map +1 -1
- package/dist/utils/html.d.ts.map +1 -1
- package/dist/utils/html.js.map +1 -1
- package/dist/utils/image-convert.d.ts.map +1 -1
- package/dist/utils/image-convert.js.map +1 -1
- package/dist/utils/image-process.d.ts.map +1 -1
- package/dist/utils/image-process.js.map +1 -1
- package/dist/utils/image-resize-core.d.ts +12 -0
- package/dist/utils/image-resize-core.d.ts.map +1 -1
- package/dist/utils/image-resize-core.js +5 -0
- package/dist/utils/image-resize-core.js.map +1 -1
- package/dist/utils/image-resize-worker.d.ts.map +1 -1
- package/dist/utils/image-resize-worker.js +3 -2
- package/dist/utils/image-resize-worker.js.map +1 -1
- package/dist/utils/image-resize.d.ts.map +1 -1
- package/dist/utils/image-resize.js +9 -10
- package/dist/utils/image-resize.js.map +1 -1
- package/dist/utils/json.d.ts.map +1 -1
- package/dist/utils/json.js.map +1 -1
- package/dist/utils/management-http.d.ts.map +1 -1
- package/dist/utils/management-http.js.map +1 -1
- package/dist/utils/mime.d.ts.map +1 -1
- package/dist/utils/mime.js +1 -1
- package/dist/utils/mime.js.map +1 -1
- package/dist/utils/oklab.d.ts +43 -0
- package/dist/utils/oklab.d.ts.map +1 -0
- package/dist/utils/oklab.js +210 -0
- package/dist/utils/oklab.js.map +1 -0
- package/dist/utils/open-browser.d.ts.map +1 -1
- package/dist/utils/open-browser.js.map +1 -1
- package/dist/utils/output-files.d.ts +15 -0
- package/dist/utils/output-files.d.ts.map +1 -0
- package/dist/utils/output-files.js +30 -0
- package/dist/utils/output-files.js.map +1 -0
- package/dist/utils/paths.d.ts +3 -3
- package/dist/utils/paths.d.ts.map +1 -1
- package/dist/utils/paths.js +5 -4
- package/dist/utils/paths.js.map +1 -1
- package/dist/utils/photon.d.ts.map +1 -1
- package/dist/utils/photon.js.map +1 -1
- package/dist/utils/pi-user-agent.d.ts.map +1 -1
- package/dist/utils/pi-user-agent.js.map +1 -1
- package/dist/utils/shell.d.ts +1 -3
- package/dist/utils/shell.d.ts.map +1 -1
- package/dist/utils/shell.js +3 -30
- package/dist/utils/shell.js.map +1 -1
- package/dist/utils/sleep.d.ts.map +1 -1
- package/dist/utils/sleep.js.map +1 -1
- package/dist/utils/syntax-highlight.d.ts.map +1 -1
- package/dist/utils/syntax-highlight.js +8 -1
- package/dist/utils/syntax-highlight.js.map +1 -1
- package/dist/utils/text.d.ts.map +1 -1
- package/dist/utils/text.js.map +1 -1
- package/dist/utils/tool-result-images.d.ts +3 -1
- package/dist/utils/tool-result-images.d.ts.map +1 -1
- package/dist/utils/tool-result-images.js +4 -1
- package/dist/utils/tool-result-images.js.map +1 -1
- package/dist/utils/tools-manager.d.ts.map +1 -1
- package/dist/utils/tools-manager.js.map +1 -1
- package/dist/utils/version-check.d.ts.map +1 -1
- package/dist/utils/version-check.js.map +1 -1
- package/dist/utils/windows-self-update.d.ts.map +1 -1
- package/dist/utils/windows-self-update.js.map +1 -1
- package/dist/utils/wsl.d.ts +3 -0
- package/dist/utils/wsl.d.ts.map +1 -0
- package/dist/utils/wsl.js +15 -0
- package/dist/utils/wsl.js.map +1 -0
- package/dist/utils/zip.d.ts +7 -0
- package/dist/utils/zip.d.ts.map +1 -0
- package/dist/utils/zip.js +60 -0
- package/dist/utils/zip.js.map +1 -0
- package/docs/cli-integration.md +106 -0
- package/docs/cli.md +333 -0
- package/docs/codemode.md +230 -0
- package/docs/compaction.md +47 -28
- package/docs/configuration.md +47 -0
- package/docs/containerization.md +109 -82
- package/docs/custom-provider.md +109 -713
- package/docs/docs.json +152 -96
- package/docs/environment-variables.md +18 -3
- package/docs/extensions.md +284 -604
- package/docs/how-pi-works.md +49 -0
- package/docs/images/interactive-mode.png +0 -0
- package/docs/index.md +24 -69
- package/docs/json.md +193 -65
- package/docs/keybindings.md +58 -103
- package/docs/llama-cpp.md +24 -4
- package/docs/mcp.md +272 -0
- package/docs/message-types.md +279 -0
- package/docs/models.md +124 -489
- package/docs/nvidia-rtx-llama-cpp.md +96 -0
- package/docs/packages.md +67 -166
- package/docs/prompt-templates.md +31 -68
- package/docs/providers.md +158 -228
- package/docs/punch-todos.md +24 -0
- package/docs/quickstart.md +61 -106
- package/docs/rpc-commands.md +888 -0
- package/docs/rpc-extension-ui.md +200 -0
- package/docs/rpc.md +131 -1554
- package/docs/sdk.md +79 -1158
- package/docs/security.md +72 -32
- package/docs/session-format.md +58 -215
- package/docs/sessions.md +35 -114
- package/docs/settings.md +98 -326
- package/docs/shell-aliases.md +85 -5
- package/docs/skills.md +51 -190
- package/docs/slash-commands.md +60 -0
- package/docs/subagents.md +2 -0
- package/docs/terminal-setup.md +7 -182
- package/docs/termux.md +74 -83
- package/docs/themes.md +89 -273
- package/docs/tmux.md +31 -39
- package/docs/tui.md +74 -910
- package/docs/usage.md +52 -129
- package/docs/virtual-models.md +114 -0
- package/docs/windows.md +45 -17
- package/examples/README.md +13 -5
- package/examples/extensions/README.md +4 -30
- package/examples/extensions/custom-provider-anthropic/index.ts +18 -12
- package/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
- package/examples/extensions/custom-provider-anthropic/package.json +17 -17
- package/examples/extensions/custom-provider-gitlab-duo/index.ts +2 -2
- package/examples/extensions/custom-provider-gitlab-duo/package.json +14 -14
- package/examples/extensions/custom-provider-gitlab-duo/test.ts +5 -5
- package/examples/extensions/debug-provider.ts +69 -0
- package/examples/extensions/dynamic-resources/dynamic.json +1 -1
- package/examples/extensions/gondolin/package-lock.json +5 -5
- package/examples/extensions/gondolin/package.json +1 -1
- package/examples/extensions/jev-router.ts +113 -0
- package/examples/extensions/prompt-customizer.ts +19 -67
- package/examples/extensions/sandbox/package-lock.json +2 -2
- package/examples/extensions/sandbox/package.json +1 -1
- package/examples/extensions/with-deps/package-lock.json +2 -2
- package/examples/extensions/with-deps/package.json +20 -20
- package/examples/rpc-client.ts +35 -0
- package/examples/sdk/14-codemode-mcp.ts +61 -0
- package/examples/sdk/README.md +3 -2
- package/npm-shrinkwrap.json +2425 -0
- package/package.json +30 -29
- package/schemas/models.schema.json +1157 -0
- package/schemas/settings.schema.json +734 -0
- package/schemas/theme.schema.json +365 -0
- package/src/extensions/punch/sqlite-bun.mjs +1 -0
- package/src/extensions/punch/sqlite-driver.d.mts +15 -0
- package/src/extensions/punch/sqlite-node.mjs +1 -0
- package/dist/bundle/chunks/anthropic-messages-ASRU76PT.js +0 -6
- package/dist/bundle/chunks/azure-openai-responses-UGF6LMEX.js +0 -2
- package/dist/bundle/chunks/chunk-5PRUVL6W.js +0 -1770
- package/dist/bundle/chunks/chunk-6R7UI4IY.js +0 -2
- package/dist/bundle/chunks/chunk-A3JYRWB6.js +0 -2
- package/dist/bundle/chunks/chunk-CHB3CEFP.js +0 -2
- package/dist/bundle/chunks/chunk-ELBMWBDG.js +0 -11
- package/dist/bundle/chunks/chunk-GMWCTUPB.js +0 -2
- package/dist/bundle/chunks/chunk-GTBU4EAF.js +0 -2
- package/dist/bundle/chunks/chunk-NUHFSC37.js +0 -25
- package/dist/bundle/chunks/chunk-UIWY7TU5.js +0 -42
- package/dist/bundle/chunks/chunk-XNGRGP62.js +0 -2
- package/dist/bundle/chunks/google-generative-ai-VCD2PGIY.js +0 -2
- package/dist/bundle/chunks/google-vertex-L6U34ZRC.js +0 -2
- package/dist/bundle/chunks/mistral-conversations-IXWQ2YKN.js +0 -5
- package/dist/bundle/chunks/node-5YXRXMVN.js +0 -16
- package/dist/bundle/chunks/openai-codex-responses-P7HKQLIT.js +0 -10
- package/dist/bundle/chunks/openai-completions-O7BFLP3U.js +0 -7
- package/dist/bundle/chunks/openai-responses-QAKWAYVG.js +0 -2
- package/dist/cli/config-selector.d.ts +0 -16
- package/dist/cli/config-selector.d.ts.map +0 -1
- package/dist/cli/config-selector.js +0 -32
- package/dist/cli/config-selector.js.map +0 -1
- package/dist/cli/session-picker.d.ts +0 -10
- package/dist/cli/session-picker.d.ts.map +0 -1
- package/dist/cli/session-picker.js +0 -36
- package/dist/cli/session-picker.js.map +0 -1
- package/dist/cli/startup-ui.d.ts +0 -20
- package/dist/cli/startup-ui.d.ts.map +0 -1
- package/dist/cli/startup-ui.js +0 -185
- package/dist/cli/startup-ui.js.map +0 -1
- package/dist/core/keybindings.d.ts +0 -428
- package/dist/core/keybindings.d.ts.map +0 -1
- package/dist/core/keybindings.js +0 -321
- package/dist/core/keybindings.js.map +0 -1
- package/dist/core/tools/render-utils.d.ts +0 -24
- package/dist/core/tools/render-utils.d.ts.map +0 -1
- package/dist/core/tools/render-utils.js +0 -65
- package/dist/core/tools/render-utils.js.map +0 -1
- package/dist/core/tools/renderers/bash.d.ts +0 -12
- package/dist/core/tools/renderers/bash.d.ts.map +0 -1
- package/dist/core/tools/renderers/bash.js +0 -130
- package/dist/core/tools/renderers/bash.js.map +0 -1
- package/dist/core/tools/renderers/edit.d.ts +0 -23
- package/dist/core/tools/renderers/edit.d.ts.map +0 -1
- package/dist/core/tools/renderers/edit.js +0 -167
- package/dist/core/tools/renderers/edit.js.map +0 -1
- package/dist/core/tools/renderers/find.d.ts +0 -10
- package/dist/core/tools/renderers/find.d.ts.map +0 -1
- package/dist/core/tools/renderers/find.js +0 -64
- package/dist/core/tools/renderers/find.js.map +0 -1
- package/dist/core/tools/renderers/grep.d.ts +0 -10
- package/dist/core/tools/renderers/grep.d.ts.map +0 -1
- package/dist/core/tools/renderers/grep.js +0 -69
- package/dist/core/tools/renderers/grep.js.map +0 -1
- package/dist/core/tools/renderers/index.d.ts +0 -28
- package/dist/core/tools/renderers/index.d.ts.map +0 -1
- package/dist/core/tools/renderers/index.js +0 -47
- package/dist/core/tools/renderers/index.js.map +0 -1
- package/dist/core/tools/renderers/ls.d.ts +0 -10
- package/dist/core/tools/renderers/ls.d.ts.map +0 -1
- package/dist/core/tools/renderers/ls.js +0 -58
- package/dist/core/tools/renderers/ls.js.map +0 -1
- package/dist/core/tools/renderers/read.d.ts +0 -11
- package/dist/core/tools/renderers/read.d.ts.map +0 -1
- package/dist/core/tools/renderers/read.js +0 -129
- package/dist/core/tools/renderers/read.js.map +0 -1
- package/dist/core/tools/renderers/write.d.ts +0 -10
- package/dist/core/tools/renderers/write.d.ts.map +0 -1
- package/dist/core/tools/renderers/write.js +0 -153
- package/dist/core/tools/renderers/write.js.map +0 -1
- package/dist/extensions/mcp/mcp-client.d.ts +0 -31
- package/dist/extensions/mcp/mcp-client.d.ts.map +0 -1
- package/dist/extensions/mcp/mcp-client.js +0 -149
- package/dist/extensions/mcp/mcp-client.js.map +0 -1
- package/dist/extensions/mcp/mcp-config.d.ts +0 -47
- package/dist/extensions/mcp/mcp-config.d.ts.map +0 -1
- package/dist/extensions/mcp/mcp-config.js +0 -281
- package/dist/extensions/mcp/mcp-config.js.map +0 -1
- package/dist/extensions/mcp/mcp-transport.d.ts +0 -65
- package/dist/extensions/mcp/mcp-transport.d.ts.map +0 -1
- package/dist/extensions/mcp/mcp-transport.js +0 -278
- package/dist/extensions/mcp/mcp-transport.js.map +0 -1
- package/dist/modes/interactive/assets/clankolas.png +0 -0
- package/dist/modes/interactive/chat-viewport.d.ts +0 -20
- package/dist/modes/interactive/chat-viewport.d.ts.map +0 -1
- package/dist/modes/interactive/chat-viewport.js +0 -28
- package/dist/modes/interactive/chat-viewport.js.map +0 -1
- package/dist/modes/interactive/components/armin.d.ts +0 -34
- package/dist/modes/interactive/components/armin.d.ts.map +0 -1
- package/dist/modes/interactive/components/armin.js +0 -333
- package/dist/modes/interactive/components/armin.js.map +0 -1
- package/dist/modes/interactive/components/assistant-message.d.ts +0 -26
- package/dist/modes/interactive/components/assistant-message.d.ts.map +0 -1
- package/dist/modes/interactive/components/assistant-message.js +0 -158
- package/dist/modes/interactive/components/assistant-message.js.map +0 -1
- package/dist/modes/interactive/components/bash-execution.d.ts +0 -34
- package/dist/modes/interactive/components/bash-execution.d.ts.map +0 -1
- package/dist/modes/interactive/components/bash-execution.js +0 -175
- package/dist/modes/interactive/components/bash-execution.js.map +0 -1
- package/dist/modes/interactive/components/bordered-loader.d.ts +0 -16
- package/dist/modes/interactive/components/bordered-loader.d.ts.map +0 -1
- package/dist/modes/interactive/components/bordered-loader.js +0 -54
- package/dist/modes/interactive/components/bordered-loader.js.map +0 -1
- package/dist/modes/interactive/components/branch-summary-message.d.ts +0 -16
- package/dist/modes/interactive/components/branch-summary-message.d.ts.map +0 -1
- package/dist/modes/interactive/components/branch-summary-message.js +0 -44
- package/dist/modes/interactive/components/branch-summary-message.js.map +0 -1
- package/dist/modes/interactive/components/compaction-summary-message.d.ts +0 -16
- package/dist/modes/interactive/components/compaction-summary-message.d.ts.map +0 -1
- package/dist/modes/interactive/components/compaction-summary-message.js +0 -45
- package/dist/modes/interactive/components/compaction-summary-message.js.map +0 -1
- package/dist/modes/interactive/components/config-selector.d.ts +0 -102
- package/dist/modes/interactive/components/config-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/config-selector.js +0 -761
- package/dist/modes/interactive/components/config-selector.js.map +0 -1
- package/dist/modes/interactive/components/countdown-timer.d.ts +0 -14
- package/dist/modes/interactive/components/countdown-timer.d.ts.map +0 -1
- package/dist/modes/interactive/components/countdown-timer.js +0 -33
- package/dist/modes/interactive/components/countdown-timer.js.map +0 -1
- package/dist/modes/interactive/components/custom-editor.d.ts +0 -30
- package/dist/modes/interactive/components/custom-editor.d.ts.map +0 -1
- package/dist/modes/interactive/components/custom-editor.js +0 -115
- package/dist/modes/interactive/components/custom-editor.js.map +0 -1
- package/dist/modes/interactive/components/custom-entry.d.ts +0 -19
- package/dist/modes/interactive/components/custom-entry.d.ts.map +0 -1
- package/dist/modes/interactive/components/custom-entry.js +0 -52
- package/dist/modes/interactive/components/custom-entry.js.map +0 -1
- package/dist/modes/interactive/components/custom-message.d.ts +0 -22
- package/dist/modes/interactive/components/custom-message.d.ts.map +0 -1
- package/dist/modes/interactive/components/custom-message.js +0 -87
- package/dist/modes/interactive/components/custom-message.js.map +0 -1
- package/dist/modes/interactive/components/daxnuts.d.ts +0 -23
- package/dist/modes/interactive/components/daxnuts.d.ts.map +0 -1
- package/dist/modes/interactive/components/daxnuts.js +0 -140
- package/dist/modes/interactive/components/daxnuts.js.map +0 -1
- package/dist/modes/interactive/components/diff.d.ts +0 -12
- package/dist/modes/interactive/components/diff.d.ts.map +0 -1
- package/dist/modes/interactive/components/diff.js +0 -133
- package/dist/modes/interactive/components/diff.js.map +0 -1
- package/dist/modes/interactive/components/dynamic-border.d.ts +0 -15
- package/dist/modes/interactive/components/dynamic-border.d.ts.map +0 -1
- package/dist/modes/interactive/components/dynamic-border.js +0 -21
- package/dist/modes/interactive/components/dynamic-border.js.map +0 -1
- package/dist/modes/interactive/components/earendil-announcement.d.ts +0 -5
- package/dist/modes/interactive/components/earendil-announcement.d.ts.map +0 -1
- package/dist/modes/interactive/components/earendil-announcement.js +0 -40
- package/dist/modes/interactive/components/earendil-announcement.js.map +0 -1
- package/dist/modes/interactive/components/extension-editor.d.ts +0 -21
- package/dist/modes/interactive/components/extension-editor.d.ts.map +0 -1
- package/dist/modes/interactive/components/extension-editor.js +0 -98
- package/dist/modes/interactive/components/extension-editor.js.map +0 -1
- package/dist/modes/interactive/components/extension-input.d.ts +0 -23
- package/dist/modes/interactive/components/extension-input.d.ts.map +0 -1
- package/dist/modes/interactive/components/extension-input.js +0 -61
- package/dist/modes/interactive/components/extension-input.js.map +0 -1
- package/dist/modes/interactive/components/extension-selector.d.ts +0 -26
- package/dist/modes/interactive/components/extension-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/extension-selector.js +0 -83
- package/dist/modes/interactive/components/extension-selector.js.map +0 -1
- package/dist/modes/interactive/components/first-time-setup.d.ts +0 -25
- package/dist/modes/interactive/components/first-time-setup.d.ts.map +0 -1
- package/dist/modes/interactive/components/first-time-setup.js +0 -103
- package/dist/modes/interactive/components/first-time-setup.js.map +0 -1
- package/dist/modes/interactive/components/footer.d.ts +0 -32
- package/dist/modes/interactive/components/footer.d.ts.map +0 -1
- package/dist/modes/interactive/components/footer.js +0 -222
- package/dist/modes/interactive/components/footer.js.map +0 -1
- package/dist/modes/interactive/components/index.d.ts +0 -34
- package/dist/modes/interactive/components/index.d.ts.map +0 -1
- package/dist/modes/interactive/components/index.js +0 -35
- package/dist/modes/interactive/components/index.js.map +0 -1
- package/dist/modes/interactive/components/keybinding-hints.d.ts +0 -13
- package/dist/modes/interactive/components/keybinding-hints.d.ts.map +0 -1
- package/dist/modes/interactive/components/keybinding-hints.js +0 -36
- package/dist/modes/interactive/components/keybinding-hints.js.map +0 -1
- package/dist/modes/interactive/components/login-dialog.d.ts +0 -52
- package/dist/modes/interactive/components/login-dialog.d.ts.map +0 -1
- package/dist/modes/interactive/components/login-dialog.js +0 -188
- package/dist/modes/interactive/components/login-dialog.js.map +0 -1
- package/dist/modes/interactive/components/markdown-transform.d.ts +0 -3
- package/dist/modes/interactive/components/markdown-transform.d.ts.map +0 -1
- package/dist/modes/interactive/components/markdown-transform.js +0 -19
- package/dist/modes/interactive/components/markdown-transform.js.map +0 -1
- package/dist/modes/interactive/components/mermaid.d.ts +0 -11
- package/dist/modes/interactive/components/mermaid.d.ts.map +0 -1
- package/dist/modes/interactive/components/mermaid.js +0 -75
- package/dist/modes/interactive/components/mermaid.js.map +0 -1
- package/dist/modes/interactive/components/model-selector.d.ts +0 -60
- package/dist/modes/interactive/components/model-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/model-selector.js +0 -361
- package/dist/modes/interactive/components/model-selector.js.map +0 -1
- package/dist/modes/interactive/components/oauth-selector.d.ts +0 -33
- package/dist/modes/interactive/components/oauth-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/oauth-selector.js +0 -163
- package/dist/modes/interactive/components/oauth-selector.js.map +0 -1
- package/dist/modes/interactive/components/question-selector.d.ts +0 -24
- package/dist/modes/interactive/components/question-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/question-selector.js +0 -158
- package/dist/modes/interactive/components/question-selector.js.map +0 -1
- package/dist/modes/interactive/components/scoped-models-selector.d.ts +0 -46
- package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/scoped-models-selector.js +0 -326
- package/dist/modes/interactive/components/scoped-models-selector.js.map +0 -1
- package/dist/modes/interactive/components/session-selector-search.d.ts +0 -23
- package/dist/modes/interactive/components/session-selector-search.d.ts.map +0 -1
- package/dist/modes/interactive/components/session-selector-search.js +0 -155
- package/dist/modes/interactive/components/session-selector-search.js.map +0 -1
- package/dist/modes/interactive/components/session-selector.d.ts +0 -95
- package/dist/modes/interactive/components/session-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/session-selector.js +0 -867
- package/dist/modes/interactive/components/session-selector.js.map +0 -1
- package/dist/modes/interactive/components/settings-selector.d.ts +0 -92
- package/dist/modes/interactive/components/settings-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/settings-selector.js +0 -709
- package/dist/modes/interactive/components/settings-selector.js.map +0 -1
- package/dist/modes/interactive/components/settings-submenu.d.ts +0 -72
- package/dist/modes/interactive/components/settings-submenu.d.ts.map +0 -1
- package/dist/modes/interactive/components/settings-submenu.js +0 -165
- package/dist/modes/interactive/components/settings-submenu.js.map +0 -1
- package/dist/modes/interactive/components/show-images-selector.d.ts +0 -10
- package/dist/modes/interactive/components/show-images-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/show-images-selector.js +0 -39
- package/dist/modes/interactive/components/show-images-selector.js.map +0 -1
- package/dist/modes/interactive/components/skill-invocation-message.d.ts +0 -17
- package/dist/modes/interactive/components/skill-invocation-message.d.ts.map +0 -1
- package/dist/modes/interactive/components/skill-invocation-message.js +0 -47
- package/dist/modes/interactive/components/skill-invocation-message.js.map +0 -1
- package/dist/modes/interactive/components/status-indicator.d.ts +0 -30
- package/dist/modes/interactive/components/status-indicator.d.ts.map +0 -1
- package/dist/modes/interactive/components/status-indicator.js +0 -67
- package/dist/modes/interactive/components/status-indicator.js.map +0 -1
- package/dist/modes/interactive/components/theme-selector.d.ts +0 -11
- package/dist/modes/interactive/components/theme-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/theme-selector.js +0 -50
- package/dist/modes/interactive/components/theme-selector.js.map +0 -1
- package/dist/modes/interactive/components/thinking-selector.d.ts +0 -23
- package/dist/modes/interactive/components/thinking-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/thinking-selector.js +0 -109
- package/dist/modes/interactive/components/thinking-selector.js.map +0 -1
- package/dist/modes/interactive/components/tool-execution.d.ts +0 -80
- package/dist/modes/interactive/components/tool-execution.d.ts.map +0 -1
- package/dist/modes/interactive/components/tool-execution.js +0 -328
- package/dist/modes/interactive/components/tool-execution.js.map +0 -1
- package/dist/modes/interactive/components/tree-selector.d.ts +0 -94
- package/dist/modes/interactive/components/tree-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/tree-selector.js +0 -1245
- package/dist/modes/interactive/components/tree-selector.js.map +0 -1
- package/dist/modes/interactive/components/trust-selector.d.ts +0 -23
- package/dist/modes/interactive/components/trust-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/trust-selector.js +0 -91
- package/dist/modes/interactive/components/trust-selector.js.map +0 -1
- package/dist/modes/interactive/components/user-message-selector.d.ts +0 -30
- package/dist/modes/interactive/components/user-message-selector.d.ts.map +0 -1
- package/dist/modes/interactive/components/user-message-selector.js +0 -114
- package/dist/modes/interactive/components/user-message-selector.js.map +0 -1
- package/dist/modes/interactive/components/user-message.d.ts +0 -16
- package/dist/modes/interactive/components/user-message.d.ts.map +0 -1
- package/dist/modes/interactive/components/user-message.js +0 -49
- package/dist/modes/interactive/components/user-message.js.map +0 -1
- package/dist/modes/interactive/components/visual-truncate.d.ts +0 -24
- package/dist/modes/interactive/components/visual-truncate.d.ts.map +0 -1
- package/dist/modes/interactive/components/visual-truncate.js +0 -33
- package/dist/modes/interactive/components/visual-truncate.js.map +0 -1
- package/dist/modes/interactive/external-editor.d.ts +0 -12
- package/dist/modes/interactive/external-editor.d.ts.map +0 -1
- package/dist/modes/interactive/external-editor.js +0 -38
- package/dist/modes/interactive/external-editor.js.map +0 -1
- package/dist/modes/interactive/interactive-mode.d.ts +0 -443
- package/dist/modes/interactive/interactive-mode.d.ts.map +0 -1
- package/dist/modes/interactive/interactive-mode.js +0 -5604
- package/dist/modes/interactive/interactive-mode.js.map +0 -1
- package/dist/modes/interactive/model-catalog-refresh.d.ts.map +0 -1
- package/dist/modes/interactive/model-catalog-refresh.js.map +0 -1
- package/dist/modes/interactive/model-search.d.ts +0 -12
- package/dist/modes/interactive/model-search.d.ts.map +0 -1
- package/dist/modes/interactive/model-search.js +0 -15
- package/dist/modes/interactive/model-search.js.map +0 -1
- package/dist/modes/interactive/session-share.d.ts +0 -16
- package/dist/modes/interactive/session-share.d.ts.map +0 -1
- package/dist/modes/interactive/session-share.js +0 -184
- package/dist/modes/interactive/session-share.js.map +0 -1
- package/dist/modes/interactive/theme/dark.json +0 -91
- package/dist/modes/interactive/theme/light.json +0 -90
- package/dist/modes/interactive/theme/theme-controller.d.ts +0 -41
- package/dist/modes/interactive/theme/theme-controller.d.ts.map +0 -1
- package/dist/modes/interactive/theme/theme-controller.js +0 -130
- package/dist/modes/interactive/theme/theme-controller.js.map +0 -1
- package/dist/modes/interactive/theme/theme-json.d.ts +0 -84
- package/dist/modes/interactive/theme/theme-json.d.ts.map +0 -1
- package/dist/modes/interactive/theme/theme-json.js +0 -130
- package/dist/modes/interactive/theme/theme-json.js.map +0 -1
- package/dist/modes/interactive/theme/theme-schema.json +0 -356
- package/dist/modes/interactive/theme/theme.d.ts +0 -131
- package/dist/modes/interactive/theme/theme.d.ts.map +0 -1
- package/dist/modes/interactive/theme/theme.js.map +0 -1
- package/dist/modes/interactive/tui-renderer.d.ts +0 -21
- package/dist/modes/interactive/tui-renderer.d.ts.map +0 -1
- package/dist/modes/interactive/tui-renderer.js +0 -66
- package/dist/modes/interactive/tui-renderer.js.map +0 -1
- package/docs/development.md +0 -90
- package/examples/extensions/border-status-editor.ts +0 -145
- package/examples/extensions/built-in-tool-renderer.ts +0 -249
- package/examples/extensions/custom-footer.ts +0 -64
- package/examples/extensions/custom-header.ts +0 -73
- package/examples/extensions/doom-overlay/README.md +0 -46
- package/examples/extensions/doom-overlay/doom/build/doom.js +0 -21
- package/examples/extensions/doom-overlay/doom/build/doom.wasm +0 -0
- package/examples/extensions/doom-overlay/doom/build.sh +0 -152
- package/examples/extensions/doom-overlay/doom/doomgeneric_pi.c +0 -72
- package/examples/extensions/doom-overlay/doom-component.ts +0 -132
- package/examples/extensions/doom-overlay/doom-engine.ts +0 -173
- package/examples/extensions/doom-overlay/doom-keys.ts +0 -104
- package/examples/extensions/doom-overlay/index.ts +0 -74
- package/examples/extensions/doom-overlay/wad-finder.ts +0 -55
- package/examples/extensions/entry-renderer.ts +0 -41
- package/examples/extensions/github-issue-autocomplete.ts +0 -185
- package/examples/extensions/handoff.ts +0 -190
- package/examples/extensions/interactive-shell.ts +0 -196
- package/examples/extensions/kimi-deferred-tools.ts +0 -61
- package/examples/extensions/message-renderer.ts +0 -59
- package/examples/extensions/minimal-mode.ts +0 -426
- package/examples/extensions/modal-editor.ts +0 -85
- package/examples/extensions/overlay-qa-tests.ts +0 -1450
- package/examples/extensions/overlay-test.ts +0 -153
- package/examples/extensions/plan-mode/README.md +0 -66
- package/examples/extensions/plan-mode/index.ts +0 -390
- package/examples/extensions/plan-mode/utils.ts +0 -168
- package/examples/extensions/preset.ts +0 -436
- package/examples/extensions/qna.ts +0 -118
- package/examples/extensions/question.ts +0 -278
- package/examples/extensions/questionnaire.ts +0 -440
- package/examples/extensions/rainbow-editor.ts +0 -88
- package/examples/extensions/snake.ts +0 -343
- package/examples/extensions/space-invaders.ts +0 -560
- package/examples/extensions/structured-output.ts +0 -65
- package/examples/extensions/summarize.ts +0 -199
- package/examples/extensions/tic-tac-toe.ts +0 -1008
- package/examples/extensions/todo.ts +0 -297
- package/examples/extensions/tools.ts +0 -146
- package/examples/extensions/truncated-tool.ts +0 -195
- package/examples/plugins/pi-example-plugin/README.md +0 -38
- package/examples/plugins/pi-example-plugin/package.json +0 -10
- package/examples/plugins/pi-example-plugin/src/contract.ts +0 -13
- package/examples/plugins/pi-example-plugin/src/session.ts +0 -23
- package/examples/plugins/pi-example-plugin/src/tui.ts +0 -31
- package/examples/rpc-extension-ui.ts +0 -641
- /package/dist/bundle/chunks/{chunk-PATAL4PO.js → chunk-7ZC4UXSL.js} +0 -0
package/docs/sdk.md
CHANGED
|
@@ -1,1226 +1,147 @@
|
|
|
1
|
-
> pi can help you use the SDK. Ask it to build an integration for your use case.
|
|
2
|
-
|
|
3
1
|
# SDK
|
|
4
2
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
**Example use cases:**
|
|
8
|
-
- Build a custom UI (web, desktop, mobile)
|
|
9
|
-
- Integrate agent capabilities into existing applications
|
|
10
|
-
- Create automated pipelines with agent reasoning
|
|
11
|
-
- Build custom tools that spawn sub-agents
|
|
12
|
-
- Test agent behavior programmatically
|
|
13
|
-
|
|
14
|
-
See [examples/sdk/](../examples/sdk/) for working examples from minimal to full control.
|
|
15
|
-
|
|
16
|
-
## Quick Start
|
|
17
|
-
|
|
18
|
-
```typescript
|
|
19
|
-
import { createAgentSession, ModelRuntime, SessionManager } from "@punch-bot/cli";
|
|
20
|
-
|
|
21
|
-
const modelRuntime = await ModelRuntime.create();
|
|
22
|
-
const { session } = await createAgentSession({
|
|
23
|
-
sessionManager: SessionManager.inMemory(),
|
|
24
|
-
modelRuntime,
|
|
25
|
-
});
|
|
26
|
-
|
|
27
|
-
session.subscribe((event) => {
|
|
28
|
-
if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
|
|
29
|
-
process.stdout.write(event.assistantMessageEvent.delta);
|
|
30
|
-
}
|
|
31
|
-
});
|
|
32
|
-
|
|
33
|
-
await session.prompt("What files are in the current directory?");
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
## Installation
|
|
37
|
-
|
|
38
|
-
```bash
|
|
39
|
-
npm install @punch-bot/cli
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
The SDK is included in the main package. No separate installation needed.
|
|
43
|
-
|
|
44
|
-
## Core Concepts
|
|
45
|
-
|
|
46
|
-
### createAgentSession()
|
|
3
|
+
`@punch-bot/cli` embeds Pi in a Node.js or Bun process. It provides direct TypeScript access to the agent, sessions, tools, models, and resources used by the command-line application.
|
|
47
4
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
`createAgentSession()` uses a `ResourceLoader` to supply extensions, skills, prompt templates, themes, and context files. If you do not provide one, it uses `DefaultResourceLoader` with standard discovery.
|
|
5
|
+
Use the SDK for in-process TypeScript integration. For a language-independent or isolated subprocess, see [CLI Integration](cli-integration.md).
|
|
51
6
|
|
|
52
7
|
```typescript
|
|
53
|
-
import { createAgentSession
|
|
8
|
+
import { createAgentSession } from "@punch-bot/cli";
|
|
54
9
|
|
|
55
|
-
// Minimal: defaults with DefaultResourceLoader
|
|
56
10
|
const { session } = await createAgentSession();
|
|
57
11
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
});
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
### AgentSession
|
|
67
|
-
|
|
68
|
-
The session manages agent lifecycle, message history, model state, compaction, and event streaming.
|
|
69
|
-
|
|
70
|
-
```typescript
|
|
71
|
-
interface AgentSession {
|
|
72
|
-
// Send a prompt and wait for completion
|
|
73
|
-
prompt(text: string, options?: PromptOptions): Promise<void>;
|
|
74
|
-
|
|
75
|
-
// Queue messages during streaming
|
|
76
|
-
steer(text: string): Promise<void>;
|
|
77
|
-
followUp(text: string): Promise<void>;
|
|
78
|
-
|
|
79
|
-
// Subscribe to events (returns unsubscribe function)
|
|
80
|
-
subscribe(listener: (event: AgentSessionEvent) => void): () => void;
|
|
81
|
-
|
|
82
|
-
// Session info
|
|
83
|
-
sessionFile: string | undefined;
|
|
84
|
-
sessionId: string;
|
|
85
|
-
|
|
86
|
-
// Model control
|
|
87
|
-
setModel(model: Model): Promise<void>;
|
|
88
|
-
setThinkingLevel(level: ThinkingLevel): void;
|
|
89
|
-
cycleModel(): Promise<ModelCycleResult | undefined>;
|
|
90
|
-
cycleThinkingLevel(): ThinkingLevel | undefined;
|
|
91
|
-
|
|
92
|
-
// State access
|
|
93
|
-
agent: Agent;
|
|
94
|
-
model: Model | undefined;
|
|
95
|
-
thinkingLevel: ThinkingLevel;
|
|
96
|
-
messages: AgentMessage[];
|
|
97
|
-
isStreaming: boolean;
|
|
98
|
-
|
|
99
|
-
// In-place tree navigation within the current session file
|
|
100
|
-
navigateTree(targetId: string, options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string }): Promise<{ editorText?: string; cancelled: boolean }>;
|
|
101
|
-
|
|
102
|
-
// Compaction
|
|
103
|
-
compact(customInstructions?: string): Promise<CompactionResult>;
|
|
104
|
-
abortCompaction(): void;
|
|
105
|
-
|
|
106
|
-
// Abort current operation
|
|
107
|
-
abort(): Promise<void>;
|
|
108
|
-
|
|
109
|
-
// Cleanup
|
|
110
|
-
dispose(): void;
|
|
12
|
+
try {
|
|
13
|
+
await session.prompt("What files are in the current directory?");
|
|
14
|
+
console.log(session.getLastAssistantText());
|
|
15
|
+
} finally {
|
|
16
|
+
session.dispose();
|
|
111
17
|
}
|
|
112
18
|
```
|
|
113
19
|
|
|
114
|
-
|
|
20
|
+
This uses the working directory, discovered resources, stored settings, and configured credentials. `prompt()` resolves when the run finishes.
|
|
115
21
|
|
|
116
|
-
|
|
22
|
+
The [complete minimal example](../examples/sdk/01-minimal.ts) also streams text events. All [SDK examples](../examples/sdk/) are typechecked with the repository.
|
|
117
23
|
|
|
118
|
-
|
|
24
|
+
<a id="session-management"></a>
|
|
119
25
|
|
|
120
|
-
|
|
121
|
-
This is the same layer used by the built-in interactive, print, and RPC modes.
|
|
26
|
+
## Session lifecycle
|
|
122
27
|
|
|
123
|
-
`
|
|
28
|
+
`createAgentSession()` creates an `AgentSession`. The session owns one conversation, its model and tools, queued messages, compaction state, and extension runtime.
|
|
124
29
|
|
|
125
|
-
|
|
126
|
-
import {
|
|
127
|
-
type CreateAgentSessionRuntimeFactory,
|
|
128
|
-
createAgentSessionFromServices,
|
|
129
|
-
createAgentSessionRuntime,
|
|
130
|
-
createAgentSessionServices,
|
|
131
|
-
getAgentDir,
|
|
132
|
-
SessionManager,
|
|
133
|
-
} from "@punch-bot/cli";
|
|
30
|
+
Read current state through `session.messages`, `session.model`, `session.thinkingLevel`, `session.systemPrompt`, and `session.getActiveToolNames()`.
|
|
134
31
|
|
|
135
|
-
|
|
136
|
-
const services = await createAgentSessionServices({ cwd });
|
|
137
|
-
return {
|
|
138
|
-
...(await createAgentSessionFromServices({
|
|
139
|
-
services,
|
|
140
|
-
sessionManager,
|
|
141
|
-
sessionStartEvent,
|
|
142
|
-
})),
|
|
143
|
-
services,
|
|
144
|
-
diagnostics: services.diagnostics,
|
|
145
|
-
};
|
|
146
|
-
};
|
|
32
|
+
`session.systemPrompt` is read-only and returns the current effective system prompt, including changes that have not yet been sent to the model. Tool changes are declared to the model before the next request.
|
|
147
33
|
|
|
148
|
-
|
|
149
|
-
cwd: process.cwd(),
|
|
150
|
-
agentDir: getAgentDir(),
|
|
151
|
-
sessionManager: SessionManager.create(process.cwd()),
|
|
152
|
-
});
|
|
153
|
-
```
|
|
34
|
+
<a id="sessionmanager-api"></a>
|
|
154
35
|
|
|
155
|
-
|
|
36
|
+
### Session storage
|
|
156
37
|
|
|
157
|
-
|
|
158
|
-
- `switchSession()`
|
|
159
|
-
- `fork()`
|
|
160
|
-
- clone flows via `fork(entryId, { position: "at" })`
|
|
161
|
-
- `importFromJsonl()`
|
|
38
|
+
Sessions are persistent by default. `SessionManager` owns the persisted or in-memory entry tree and tracks its active leaf. Branching changes that leaf without deleting abandoned branches. When Pi reconstructs model context, the manager selects the active branch and applies compaction.
|
|
162
39
|
|
|
163
|
-
|
|
40
|
+
`SessionManager` is authoritative for finalized model context. Restore external history by constructing the session with a manager containing those entries. Assigning `session.agent.state.messages` does not replace persisted context.
|
|
164
41
|
|
|
165
|
-
-
|
|
166
|
-
- event subscriptions are attached to a specific `AgentSession`, so re-subscribe after replacement
|
|
167
|
-
- if you use extensions, call `runtime.session.bindExtensions(...)` again for the new session
|
|
168
|
-
- creation returns diagnostics on `runtime.diagnostics`
|
|
169
|
-
- if runtime creation or replacement fails, the method throws and the caller decides how to handle it
|
|
170
|
-
|
|
171
|
-
```typescript
|
|
172
|
-
let session = runtime.session;
|
|
173
|
-
let unsubscribe = session.subscribe(() => {});
|
|
174
|
-
|
|
175
|
-
await runtime.newSession();
|
|
176
|
-
|
|
177
|
-
unsubscribe();
|
|
178
|
-
session = runtime.session;
|
|
179
|
-
unsubscribe = session.subscribe(() => {});
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
### Prompting and Message Queueing
|
|
183
|
-
|
|
184
|
-
`PromptOptions` controls prompt expansion, queueing behavior while streaming, and prompt preflight notifications:
|
|
185
|
-
|
|
186
|
-
```typescript
|
|
187
|
-
interface PromptOptions {
|
|
188
|
-
expandPromptTemplates?: boolean;
|
|
189
|
-
images?: ImageContent[];
|
|
190
|
-
streamingBehavior?: "steer" | "followUp";
|
|
191
|
-
source?: InputSource;
|
|
192
|
-
preflightResult?: (success: boolean) => void;
|
|
193
|
-
}
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
`preflightResult` is called once per `prompt()` invocation:
|
|
197
|
-
|
|
198
|
-
- `true` when the prompt was accepted, queued, or handled immediately
|
|
199
|
-
- `false` when prompt preflight rejected before acceptance
|
|
200
|
-
|
|
201
|
-
It fires before `prompt()` resolves. `prompt()` still resolves only after the full accepted run finishes, including retries. Failures after acceptance are reported through the normal event and message stream, not through `preflightResult(false)`.
|
|
202
|
-
|
|
203
|
-
The `prompt()` method handles prompt templates, extension commands, and message sending:
|
|
204
|
-
|
|
205
|
-
```typescript
|
|
206
|
-
// Basic prompt (when not streaming)
|
|
207
|
-
await session.prompt("What files are here?");
|
|
208
|
-
|
|
209
|
-
// With images
|
|
210
|
-
await session.prompt("What's in this image?", {
|
|
211
|
-
images: [{ type: "image", source: { type: "base64", mediaType: "image/png", data: "..." } }]
|
|
212
|
-
});
|
|
213
|
-
|
|
214
|
-
// During streaming: must specify how to queue the message
|
|
215
|
-
await session.prompt("Stop and do this instead", { streamingBehavior: "steer" });
|
|
216
|
-
await session.prompt("After you're done, also check X", { streamingBehavior: "followUp" });
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
**Behavior:**
|
|
220
|
-
- **Extension commands** (e.g., `/mycommand`): Execute immediately, even during streaming. They manage their own LLM interaction via `pi.sendMessage()`.
|
|
221
|
-
- **File-based prompt templates** (from `.md` files): Expanded to their content before sending or queueing.
|
|
222
|
-
- **During streaming without `streamingBehavior`**: Throws an error. Use `steer()` or `followUp()` directly, or specify the option.
|
|
223
|
-
- **`preflightResult(true)`**: Means the prompt was accepted, queued, or handled immediately.
|
|
224
|
-
- **`preflightResult(false)`**: Means preflight rejected before acceptance.
|
|
225
|
-
|
|
226
|
-
For explicit queueing during streaming:
|
|
227
|
-
|
|
228
|
-
```typescript
|
|
229
|
-
// Queue a steering message for delivery after the current assistant turn finishes its tool calls
|
|
230
|
-
await session.steer("New instruction");
|
|
231
|
-
|
|
232
|
-
// Wait for agent to finish (delivered only when agent stops)
|
|
233
|
-
await session.followUp("After you're done, also do this");
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
Both `steer()` and `followUp()` expand file-based prompt templates but error on extension commands (extension commands cannot be queued).
|
|
237
|
-
|
|
238
|
-
### Agent and AgentState
|
|
239
|
-
|
|
240
|
-
The `Agent` class (from `@punch-bot/agent`) handles the core LLM interaction. Access it via `session.agent`.
|
|
241
|
-
|
|
242
|
-
```typescript
|
|
243
|
-
// Access current state
|
|
244
|
-
const state = session.agent.state;
|
|
245
|
-
|
|
246
|
-
// state.messages: AgentMessage[] - conversation history
|
|
247
|
-
// state.model: Model - current model
|
|
248
|
-
// state.thinkingLevel: ThinkingLevel - current thinking level
|
|
249
|
-
// state.systemPrompt: string - system prompt
|
|
250
|
-
// state.tools: AgentTool[] - available tools
|
|
251
|
-
// state.streamingMessage?: AgentMessage - current partial assistant message
|
|
252
|
-
// state.errorMessage?: string - latest assistant error
|
|
253
|
-
|
|
254
|
-
// Replace messages (useful for branching or restoration)
|
|
255
|
-
session.agent.state.messages = messages; // copies the top-level array
|
|
256
|
-
|
|
257
|
-
// Replace tools
|
|
258
|
-
session.agent.state.tools = tools; // copies the top-level array
|
|
259
|
-
|
|
260
|
-
// Wait for agent to finish processing
|
|
261
|
-
await session.agent.waitForIdle();
|
|
262
|
-
```
|
|
263
|
-
|
|
264
|
-
### Events
|
|
265
|
-
|
|
266
|
-
Subscribe to events to receive streaming output and lifecycle notifications.
|
|
267
|
-
|
|
268
|
-
```typescript
|
|
269
|
-
session.subscribe((event) => {
|
|
270
|
-
switch (event.type) {
|
|
271
|
-
// Streaming text from assistant
|
|
272
|
-
case "message_update":
|
|
273
|
-
if (event.assistantMessageEvent.type === "text_delta") {
|
|
274
|
-
process.stdout.write(event.assistantMessageEvent.delta);
|
|
275
|
-
}
|
|
276
|
-
if (event.assistantMessageEvent.type === "thinking_delta") {
|
|
277
|
-
// Thinking output (if thinking enabled)
|
|
278
|
-
}
|
|
279
|
-
break;
|
|
280
|
-
|
|
281
|
-
// Tool execution
|
|
282
|
-
case "tool_execution_start":
|
|
283
|
-
console.log(`Tool: ${event.toolName}`);
|
|
284
|
-
break;
|
|
285
|
-
case "tool_execution_update":
|
|
286
|
-
// Streaming tool output
|
|
287
|
-
break;
|
|
288
|
-
case "tool_execution_end":
|
|
289
|
-
console.log(`Result: ${event.isError ? "error" : "success"}`);
|
|
290
|
-
break;
|
|
291
|
-
|
|
292
|
-
// Message lifecycle
|
|
293
|
-
case "message_start":
|
|
294
|
-
// New message starting
|
|
295
|
-
break;
|
|
296
|
-
case "message_end":
|
|
297
|
-
// Message complete
|
|
298
|
-
break;
|
|
299
|
-
|
|
300
|
-
// Agent lifecycle
|
|
301
|
-
case "agent_start":
|
|
302
|
-
// Agent started processing prompt
|
|
303
|
-
break;
|
|
304
|
-
case "agent_end":
|
|
305
|
-
// Agent finished (event.messages contains new messages)
|
|
306
|
-
break;
|
|
307
|
-
|
|
308
|
-
// Turn lifecycle (one LLM response + tool calls)
|
|
309
|
-
case "turn_start":
|
|
310
|
-
break;
|
|
311
|
-
case "turn_end":
|
|
312
|
-
// event.message: assistant response
|
|
313
|
-
// event.toolResults: tool results from this turn
|
|
314
|
-
break;
|
|
315
|
-
|
|
316
|
-
// Session events (queue, compaction, retry)
|
|
317
|
-
case "queue_update":
|
|
318
|
-
console.log(event.steering, event.followUp);
|
|
319
|
-
break;
|
|
320
|
-
case "compaction_start":
|
|
321
|
-
case "compaction_end":
|
|
322
|
-
case "auto_retry_start":
|
|
323
|
-
case "auto_retry_end":
|
|
324
|
-
case "summarization_retry_scheduled":
|
|
325
|
-
case "summarization_retry_attempt_start":
|
|
326
|
-
case "summarization_retry_finished":
|
|
327
|
-
break;
|
|
328
|
-
}
|
|
329
|
-
});
|
|
330
|
-
```
|
|
331
|
-
|
|
332
|
-
## Options Reference
|
|
333
|
-
|
|
334
|
-
### Directories
|
|
335
|
-
|
|
336
|
-
```typescript
|
|
337
|
-
const { session } = await createAgentSession({
|
|
338
|
-
// Working directory for DefaultResourceLoader discovery
|
|
339
|
-
cwd: process.cwd(), // default
|
|
340
|
-
|
|
341
|
-
// Global config directory
|
|
342
|
-
agentDir: "~/.pi/agent", // default (expands ~)
|
|
343
|
-
});
|
|
344
|
-
```
|
|
345
|
-
|
|
346
|
-
`cwd` is used by `DefaultResourceLoader` for:
|
|
347
|
-
- Project extensions (`.pi/extensions/`)
|
|
348
|
-
- Project skills:
|
|
349
|
-
- `.pi/skills/`
|
|
350
|
-
- `.agents/skills/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
|
|
351
|
-
- Project prompts (`.pi/prompts/`)
|
|
352
|
-
- Context files (`AGENTS.md` walking up from cwd)
|
|
353
|
-
- Session directory naming
|
|
354
|
-
|
|
355
|
-
`agentDir` is used by `DefaultResourceLoader` for:
|
|
356
|
-
- Global extensions (`extensions/`)
|
|
357
|
-
- Global skills:
|
|
358
|
-
- `skills/` under `agentDir` (for example `~/.pi/agent/skills/`)
|
|
359
|
-
- `~/.agents/skills/`
|
|
360
|
-
- Global prompts (`prompts/`)
|
|
361
|
-
- Global context file (`AGENTS.md`)
|
|
362
|
-
- Settings (`settings.json`)
|
|
363
|
-
- Custom models (`models.json`)
|
|
364
|
-
- Credentials (`auth.json`)
|
|
365
|
-
- Sessions (`sessions/`)
|
|
366
|
-
|
|
367
|
-
When you pass a custom `ResourceLoader`, `cwd` and `agentDir` no longer control resource discovery. They still influence session naming and tool path resolution.
|
|
368
|
-
|
|
369
|
-
### Model
|
|
370
|
-
|
|
371
|
-
```typescript
|
|
372
|
-
import { getModel } from "@punch-bot/ai";
|
|
373
|
-
import { ModelRuntime } from "@punch-bot/cli";
|
|
374
|
-
|
|
375
|
-
const modelRuntime = await ModelRuntime.create();
|
|
376
|
-
|
|
377
|
-
// create() restores cached catalogs but does not refresh them from pi.dev by default.
|
|
378
|
-
// Opt in to a create-time network refresh and bound how long it may take:
|
|
379
|
-
const refreshedRuntime = await ModelRuntime.create({
|
|
380
|
-
allowModelNetwork: true,
|
|
381
|
-
modelRefreshTimeoutMs: 15_000,
|
|
382
|
-
});
|
|
383
|
-
|
|
384
|
-
// Find specific built-in model (doesn't check if API key exists)
|
|
385
|
-
const opus = getModel("anthropic", "claude-opus-4-5");
|
|
386
|
-
if (!opus) throw new Error("Model not found");
|
|
387
|
-
|
|
388
|
-
// Find any model by provider/id, including custom models from models.json
|
|
389
|
-
// (doesn't check if API key exists)
|
|
390
|
-
const customModel = modelRuntime.getModel("my-provider", "my-model");
|
|
391
|
-
|
|
392
|
-
// Get only models that have valid authentication configured
|
|
393
|
-
const available = await modelRuntime.getAvailable();
|
|
394
|
-
|
|
395
|
-
const { session } = await createAgentSession({
|
|
396
|
-
model: opus,
|
|
397
|
-
thinkingLevel: "medium", // off, minimal, low, medium, high, xhigh, max
|
|
398
|
-
|
|
399
|
-
// Models for cycling (Ctrl+P in interactive mode)
|
|
400
|
-
scopedModels: [
|
|
401
|
-
{ model: opus, thinkingLevel: "high" },
|
|
402
|
-
{ model: haiku, thinkingLevel: "off" },
|
|
403
|
-
],
|
|
404
|
-
|
|
405
|
-
modelRuntime,
|
|
406
|
-
});
|
|
407
|
-
```
|
|
408
|
-
|
|
409
|
-
If no model is provided:
|
|
410
|
-
1. Tries to restore from session (if continuing)
|
|
411
|
-
2. Uses default from settings
|
|
412
|
-
3. Falls back to first available model
|
|
413
|
-
|
|
414
|
-
Remote catalogs are persisted locally so later runtimes can restore them without a network request. The default file is `~/.pi/agent/models-store.json`; set `modelsStorePath` to choose another location, or inject `modelsStore` to control persistence. Network refreshes are throttled to once per provider every four hours unless forced. To force an immediate refresh, call `await modelRuntime.refresh({ allowNetwork: true, force: true, signal })`. Setting `PI_OFFLINE` disables model network access.
|
|
415
|
-
|
|
416
|
-
To match CLI model parsing, use the exported resolver helpers:
|
|
417
|
-
|
|
418
|
-
```typescript
|
|
419
|
-
import {
|
|
420
|
-
resolveCliModel,
|
|
421
|
-
resolveModelScopeWithDiagnostics,
|
|
422
|
-
} from "@punch-bot/cli";
|
|
423
|
-
|
|
424
|
-
const cliModel = resolveCliModel({
|
|
425
|
-
cliModel: "anthropic/claude-opus-4-5:high",
|
|
426
|
-
modelRuntime,
|
|
427
|
-
});
|
|
428
|
-
if (cliModel.error) throw new Error(cliModel.error);
|
|
429
|
-
if (cliModel.warning) console.warn(cliModel.warning);
|
|
430
|
-
|
|
431
|
-
const { scopedModels, diagnostics } = await resolveModelScopeWithDiagnostics(
|
|
432
|
-
["anthropic/*:high", "gpt-5"],
|
|
433
|
-
modelRuntime,
|
|
434
|
-
);
|
|
435
|
-
for (const diagnostic of diagnostics) {
|
|
436
|
-
console.warn(diagnostic.message);
|
|
437
|
-
}
|
|
438
|
-
```
|
|
439
|
-
|
|
440
|
-
`resolveCliModel()` uses all registered models so `--api-key` style first-time setup can resolve a model before stored auth exists. `resolveModelScopeWithDiagnostics()` matches `--models` and `enabledModels` semantics while returning warnings instead of printing them.
|
|
441
|
-
|
|
442
|
-
> See [examples/sdk/02-custom-model.ts](../examples/sdk/02-custom-model.ts)
|
|
443
|
-
|
|
444
|
-
### API Keys and OAuth
|
|
445
|
-
|
|
446
|
-
Authentication resolution priority (handled by `ModelRuntime`):
|
|
447
|
-
1. Runtime overrides (via `setRuntimeApiKey`, not persisted)
|
|
448
|
-
2. Stored credentials in `auth.json` (API keys or OAuth tokens)
|
|
449
|
-
3. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
|
|
450
|
-
4. Fallback resolver (for custom provider keys from `models.json`)
|
|
451
|
-
|
|
452
|
-
```typescript
|
|
453
|
-
import { InMemoryCredentialStore } from "@punch-bot/ai";
|
|
454
|
-
import { createAgentSession, ModelRuntime } from "@punch-bot/cli";
|
|
455
|
-
|
|
456
|
-
// Default: uses ~/.pi/agent/auth.json and ~/.pi/agent/models.json
|
|
457
|
-
const modelRuntime = await ModelRuntime.create();
|
|
458
|
-
|
|
459
|
-
// Provider-owned auth methods and current status
|
|
460
|
-
for (const provider of modelRuntime.getProviders()) {
|
|
461
|
-
const status = await modelRuntime.checkAuth(provider.id);
|
|
462
|
-
console.log(provider.name, provider.auth, status);
|
|
463
|
-
}
|
|
464
|
-
|
|
465
|
-
// Runtime API key override (not persisted to disk)
|
|
466
|
-
await modelRuntime.setRuntimeApiKey("anthropic", "sk-my-temp-key");
|
|
467
|
-
|
|
468
|
-
// Custom credential and model locations
|
|
469
|
-
const customRuntime = await ModelRuntime.create({
|
|
470
|
-
authPath: "/my/app/auth.json",
|
|
471
|
-
modelsPath: "/my/app/models.json",
|
|
472
|
-
});
|
|
473
|
-
|
|
474
|
-
// Or inject any pi-ai CredentialStore
|
|
475
|
-
const credentials = new InMemoryCredentialStore();
|
|
476
|
-
const inMemoryRuntime = await ModelRuntime.create({ credentials });
|
|
477
|
-
|
|
478
|
-
const { session } = await createAgentSession({
|
|
479
|
-
modelRuntime: customRuntime,
|
|
480
|
-
});
|
|
481
|
-
```
|
|
482
|
-
|
|
483
|
-
`login()`, `logout()`, `setRuntimeApiKey()`, and `removeRuntimeApiKey()` resolve after the affected provider's cached/built-in catalog, composition, and availability snapshot are locally consistent. They do not wait for remote catalog freshness. If credentials were committed but local synchronization fails, they reject with the exported `CredentialSynchronizationError`; inspect its `providerId`, `operation`, `credential`, and `cause` fields instead of retrying the credential mutation blindly.
|
|
484
|
-
|
|
485
|
-
Public model/auth operations and `ModelRuntime.create({ signal })` accept optional abort signals and are unbounded when omitted. SDK applications own deadline policy for remote catalog freshness:
|
|
486
|
-
|
|
487
|
-
```typescript
|
|
488
|
-
const signal = AbortSignal.timeout(15_000);
|
|
489
|
-
const result = await modelRuntime.refresh({
|
|
490
|
-
providers: ["anthropic"],
|
|
491
|
-
signal,
|
|
492
|
-
});
|
|
493
|
-
if (result.aborted) console.warn("Catalog refresh timed out; using cached models");
|
|
494
|
-
for (const [providerId, error] of result.errors) {
|
|
495
|
-
console.warn(`Could not refresh ${providerId}:`, error);
|
|
496
|
-
}
|
|
497
|
-
```
|
|
498
|
-
|
|
499
|
-
A failed or timed-out network refresh does not undo a successful credential operation. `refresh()` starts a new provider generation, so it does not wait behind an older stalled refresh and stale generations cannot publish afterward.
|
|
500
|
-
|
|
501
|
-
> See [examples/sdk/09-api-keys-and-oauth.ts](../examples/sdk/09-api-keys-and-oauth.ts)
|
|
502
|
-
|
|
503
|
-
### System Prompt
|
|
504
|
-
|
|
505
|
-
Use a `ResourceLoader` to override the system prompt:
|
|
506
|
-
|
|
507
|
-
```typescript
|
|
508
|
-
import { createAgentSession, DefaultResourceLoader } from "@punch-bot/cli";
|
|
509
|
-
|
|
510
|
-
const loader = new DefaultResourceLoader({
|
|
511
|
-
systemPromptOverride: () => "You are a helpful assistant.",
|
|
512
|
-
});
|
|
513
|
-
await loader.reload();
|
|
514
|
-
|
|
515
|
-
const { session } = await createAgentSession({ resourceLoader: loader });
|
|
516
|
-
```
|
|
517
|
-
|
|
518
|
-
> See [examples/sdk/03-custom-prompt.ts](../examples/sdk/03-custom-prompt.ts)
|
|
519
|
-
|
|
520
|
-
### Tools
|
|
521
|
-
|
|
522
|
-
Specify which built-in tools to enable:
|
|
523
|
-
|
|
524
|
-
- Built-in tool names: `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`
|
|
525
|
-
- Default built-ins: `read`, `bash`, `edit`, `write`
|
|
526
|
-
- `noTools: "all"` disables all tools
|
|
527
|
-
- `noTools: "builtin"` disables default built-ins while keeping extension and custom tools enabled
|
|
528
|
-
- `excludeTools` disables specific built-in, extension, or custom tool names after any `tools` allowlist is applied
|
|
529
|
-
|
|
530
|
-
The `edit` tool returns `details.diff` for Pi's TUI display and `details.patch` as a standard unified patch for SDK consumers.
|
|
531
|
-
|
|
532
|
-
```typescript
|
|
533
|
-
import { createAgentSession } from "@punch-bot/cli";
|
|
534
|
-
|
|
535
|
-
// Read-only mode
|
|
536
|
-
const { session } = await createAgentSession({
|
|
537
|
-
tools: ["read", "grep", "find", "ls"],
|
|
538
|
-
});
|
|
539
|
-
|
|
540
|
-
// Pick specific tools
|
|
541
|
-
const { session } = await createAgentSession({
|
|
542
|
-
tools: ["read", "bash", "grep"],
|
|
543
|
-
});
|
|
544
|
-
|
|
545
|
-
// Use PowerShell instead of Bash on Windows
|
|
546
|
-
const { session } = await createAgentSession({
|
|
547
|
-
tools: ["read", "powershell", "edit", "write"],
|
|
548
|
-
});
|
|
549
|
-
|
|
550
|
-
// Disable one tool while keeping the rest available
|
|
551
|
-
const { session } = await createAgentSession({
|
|
552
|
-
excludeTools: ["ask_question"],
|
|
553
|
-
});
|
|
554
|
-
```
|
|
555
|
-
|
|
556
|
-
#### Tools with Custom cwd
|
|
557
|
-
|
|
558
|
-
When you pass a custom `cwd`, `createAgentSession()` builds selected built-in tools for that cwd.
|
|
42
|
+
Use an in-memory manager when the host does not want session files:
|
|
559
43
|
|
|
560
44
|
```typescript
|
|
561
45
|
import { createAgentSession, SessionManager } from "@punch-bot/cli";
|
|
562
46
|
|
|
563
|
-
const cwd = "/path/to/project";
|
|
564
|
-
|
|
565
|
-
// Use default tools for custom cwd
|
|
566
47
|
const { session } = await createAgentSession({
|
|
567
|
-
cwd,
|
|
568
|
-
sessionManager: SessionManager.inMemory(cwd),
|
|
569
|
-
});
|
|
570
|
-
|
|
571
|
-
// Or pick specific tools for custom cwd
|
|
572
|
-
const { session } = await createAgentSession({
|
|
573
|
-
cwd,
|
|
574
|
-
tools: ["read", "bash", "grep"],
|
|
575
|
-
sessionManager: SessionManager.inMemory(cwd),
|
|
576
|
-
});
|
|
577
|
-
```
|
|
578
|
-
|
|
579
|
-
> See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
|
|
580
|
-
|
|
581
|
-
### Custom Tools
|
|
582
|
-
|
|
583
|
-
```typescript
|
|
584
|
-
import { Type } from "typebox";
|
|
585
|
-
import { createAgentSession, defineTool } from "@punch-bot/cli";
|
|
586
|
-
|
|
587
|
-
// Inline custom tool
|
|
588
|
-
const myTool = defineTool({
|
|
589
|
-
name: "my_tool",
|
|
590
|
-
label: "My Tool",
|
|
591
|
-
description: "Does something useful",
|
|
592
|
-
parameters: Type.Object({
|
|
593
|
-
input: Type.String({ description: "Input value" }),
|
|
594
|
-
}),
|
|
595
|
-
execute: async (_toolCallId, params) => ({
|
|
596
|
-
content: [{ type: "text", text: `Result: ${params.input}` }],
|
|
597
|
-
details: {},
|
|
598
|
-
}),
|
|
599
|
-
});
|
|
600
|
-
|
|
601
|
-
// Pass custom tools directly
|
|
602
|
-
const { session } = await createAgentSession({
|
|
603
|
-
customTools: [myTool],
|
|
604
|
-
});
|
|
605
|
-
```
|
|
606
|
-
|
|
607
|
-
Use `defineTool()` for standalone definitions and arrays like `customTools: [myTool]`. Inline `pi.registerTool({ ... })` already infers parameter types correctly.
|
|
608
|
-
|
|
609
|
-
Custom tools passed via `customTools` are combined with extension-registered tools. Extensions loaded by the ResourceLoader can also register tools via `pi.registerTool()`.
|
|
610
|
-
|
|
611
|
-
If you pass `tools`, include each custom or extension tool name you want enabled, for example `tools: ["read", "bash", "my_tool"]`.
|
|
612
|
-
|
|
613
|
-
> See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
|
|
614
|
-
|
|
615
|
-
### Extensions
|
|
616
|
-
|
|
617
|
-
Extensions are loaded by the `ResourceLoader`. `DefaultResourceLoader` discovers extensions from `~/.pi/agent/extensions/`, `.pi/extensions/`, and settings.json extension sources.
|
|
618
|
-
|
|
619
|
-
```typescript
|
|
620
|
-
import { createAgentSession, DefaultResourceLoader } from "@punch-bot/cli";
|
|
621
|
-
|
|
622
|
-
const loader = new DefaultResourceLoader({
|
|
623
|
-
additionalExtensionPaths: ["/path/to/my-extension.ts"],
|
|
624
|
-
extensionFactories: [
|
|
625
|
-
(pi) => {
|
|
626
|
-
pi.on("agent_start", () => {
|
|
627
|
-
console.log("[Inline Extension] Agent starting");
|
|
628
|
-
});
|
|
629
|
-
},
|
|
630
|
-
],
|
|
631
|
-
});
|
|
632
|
-
await loader.reload();
|
|
633
|
-
|
|
634
|
-
const { session } = await createAgentSession({ resourceLoader: loader });
|
|
635
|
-
```
|
|
636
|
-
|
|
637
|
-
Extensions can register tools, subscribe to events, add commands, and more. See [extensions.md](extensions.md) for the full API.
|
|
638
|
-
|
|
639
|
-
**Named inline extensions:** By default, inline factories display as `<inline:1>`, `<inline:2>`, etc. in the startup Extensions list. To show a descriptive name instead, wrap the factory:
|
|
640
|
-
|
|
641
|
-
```typescript
|
|
642
|
-
import type { InlineExtension } from "@punch-bot/cli";
|
|
643
|
-
|
|
644
|
-
const myProvider: InlineExtension = {
|
|
645
|
-
name: "my-provider",
|
|
646
|
-
factory: (pi) => {
|
|
647
|
-
pi.on("agent_start", () => {
|
|
648
|
-
console.log("[my-provider] Agent starting");
|
|
649
|
-
});
|
|
650
|
-
},
|
|
651
|
-
};
|
|
652
|
-
|
|
653
|
-
const loader = new DefaultResourceLoader({
|
|
654
|
-
extensionFactories: [myProvider],
|
|
655
|
-
});
|
|
656
|
-
```
|
|
657
|
-
|
|
658
|
-
This displays as `<inline:my-provider>` instead of `<inline:1>`. Bare factory functions are still accepted for backward compatibility.
|
|
659
|
-
|
|
660
|
-
**Event Bus:** Extensions can communicate via `pi.events`. Pass a shared `eventBus` to `DefaultResourceLoader` if you need to emit or listen from outside:
|
|
661
|
-
|
|
662
|
-
```typescript
|
|
663
|
-
import { createEventBus, DefaultResourceLoader } from "@punch-bot/cli";
|
|
664
|
-
|
|
665
|
-
const eventBus = createEventBus();
|
|
666
|
-
const loader = new DefaultResourceLoader({
|
|
667
|
-
eventBus,
|
|
668
|
-
});
|
|
669
|
-
await loader.reload();
|
|
670
|
-
|
|
671
|
-
eventBus.on("my-extension:status", (data) => console.log(data));
|
|
672
|
-
```
|
|
673
|
-
|
|
674
|
-
> See [examples/sdk/06-extensions.ts](../examples/sdk/06-extensions.ts) and [docs/extensions.md](extensions.md)
|
|
675
|
-
|
|
676
|
-
### Skills
|
|
677
|
-
|
|
678
|
-
```typescript
|
|
679
|
-
import {
|
|
680
|
-
createAgentSession,
|
|
681
|
-
DefaultResourceLoader,
|
|
682
|
-
type Skill,
|
|
683
|
-
} from "@punch-bot/cli";
|
|
684
|
-
|
|
685
|
-
const customSkill: Skill = {
|
|
686
|
-
name: "my-skill",
|
|
687
|
-
description: "Custom instructions",
|
|
688
|
-
filePath: "/path/to/SKILL.md",
|
|
689
|
-
baseDir: "/path/to",
|
|
690
|
-
source: "custom",
|
|
691
|
-
};
|
|
692
|
-
|
|
693
|
-
const loader = new DefaultResourceLoader({
|
|
694
|
-
skillsOverride: (current) => ({
|
|
695
|
-
skills: [...current.skills, customSkill],
|
|
696
|
-
diagnostics: current.diagnostics,
|
|
697
|
-
}),
|
|
698
|
-
});
|
|
699
|
-
await loader.reload();
|
|
700
|
-
|
|
701
|
-
const { session } = await createAgentSession({ resourceLoader: loader });
|
|
702
|
-
```
|
|
703
|
-
|
|
704
|
-
> See [examples/sdk/04-skills.ts](../examples/sdk/04-skills.ts)
|
|
705
|
-
|
|
706
|
-
### Context Files
|
|
707
|
-
|
|
708
|
-
```typescript
|
|
709
|
-
import { createAgentSession, DefaultResourceLoader } from "@punch-bot/cli";
|
|
710
|
-
|
|
711
|
-
const loader = new DefaultResourceLoader({
|
|
712
|
-
agentsFilesOverride: (current) => ({
|
|
713
|
-
agentsFiles: [
|
|
714
|
-
...current.agentsFiles,
|
|
715
|
-
{ path: "/virtual/AGENTS.md", content: "# Guidelines\n\n- Be concise" },
|
|
716
|
-
],
|
|
717
|
-
}),
|
|
718
|
-
});
|
|
719
|
-
await loader.reload();
|
|
720
|
-
|
|
721
|
-
const { session } = await createAgentSession({ resourceLoader: loader });
|
|
722
|
-
```
|
|
723
|
-
|
|
724
|
-
> See [examples/sdk/07-context-files.ts](../examples/sdk/07-context-files.ts)
|
|
725
|
-
|
|
726
|
-
### Slash Commands
|
|
727
|
-
|
|
728
|
-
```typescript
|
|
729
|
-
import {
|
|
730
|
-
createAgentSession,
|
|
731
|
-
DefaultResourceLoader,
|
|
732
|
-
type PromptTemplate,
|
|
733
|
-
} from "@punch-bot/cli";
|
|
734
|
-
|
|
735
|
-
const customCommand: PromptTemplate = {
|
|
736
|
-
name: "deploy",
|
|
737
|
-
description: "Deploy the application",
|
|
738
|
-
source: "(custom)",
|
|
739
|
-
content: "# Deploy\n\n1. Build\n2. Test\n3. Deploy",
|
|
740
|
-
};
|
|
741
|
-
|
|
742
|
-
const loader = new DefaultResourceLoader({
|
|
743
|
-
promptsOverride: (current) => ({
|
|
744
|
-
prompts: [...current.prompts, customCommand],
|
|
745
|
-
diagnostics: current.diagnostics,
|
|
746
|
-
}),
|
|
747
|
-
});
|
|
748
|
-
await loader.reload();
|
|
749
|
-
|
|
750
|
-
const { session } = await createAgentSession({ resourceLoader: loader });
|
|
751
|
-
```
|
|
752
|
-
|
|
753
|
-
> See [examples/sdk/08-prompt-templates.ts](../examples/sdk/08-prompt-templates.ts)
|
|
754
|
-
|
|
755
|
-
### Session Management
|
|
756
|
-
|
|
757
|
-
Sessions use a tree structure with `id`/`parentId` linking, enabling in-place branching.
|
|
758
|
-
|
|
759
|
-
```typescript
|
|
760
|
-
import {
|
|
761
|
-
type CreateAgentSessionRuntimeFactory,
|
|
762
|
-
createAgentSession,
|
|
763
|
-
createAgentSessionFromServices,
|
|
764
|
-
createAgentSessionRuntime,
|
|
765
|
-
createAgentSessionServices,
|
|
766
|
-
getAgentDir,
|
|
767
|
-
SessionManager,
|
|
768
|
-
} from "@punch-bot/cli";
|
|
769
|
-
|
|
770
|
-
// In-memory (no persistence)
|
|
771
|
-
const { session } = await createAgentSession({
|
|
772
|
-
sessionManager: SessionManager.inMemory(),
|
|
773
|
-
});
|
|
774
|
-
|
|
775
|
-
// New persistent session
|
|
776
|
-
const { session: persisted } = await createAgentSession({
|
|
777
|
-
sessionManager: SessionManager.create(process.cwd()),
|
|
778
|
-
});
|
|
779
|
-
|
|
780
|
-
// Continue most recent
|
|
781
|
-
const { session: continued, modelFallbackMessage } = await createAgentSession({
|
|
782
|
-
sessionManager: SessionManager.continueRecent(process.cwd()),
|
|
783
|
-
});
|
|
784
|
-
if (modelFallbackMessage) {
|
|
785
|
-
console.log("Note:", modelFallbackMessage);
|
|
786
|
-
}
|
|
787
|
-
|
|
788
|
-
// Open specific file
|
|
789
|
-
const { session: opened } = await createAgentSession({
|
|
790
|
-
sessionManager: SessionManager.open("/path/to/session.jsonl"),
|
|
791
|
-
});
|
|
792
|
-
|
|
793
|
-
// Resume a session kept outside the filesystem, e.g. in a database
|
|
794
|
-
const { session: restored } = await createAgentSession({
|
|
795
|
-
sessionManager: SessionManager.inMemory(process.cwd(), { id: sessionId }, entries),
|
|
796
|
-
});
|
|
797
|
-
|
|
798
|
-
// List sessions
|
|
799
|
-
const currentProjectSessions = await SessionManager.list(process.cwd());
|
|
800
|
-
const allSessions = await SessionManager.listAll(process.cwd());
|
|
801
|
-
|
|
802
|
-
// Session replacement API for /new, /resume, /fork, /clone, and import flows.
|
|
803
|
-
const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
|
|
804
|
-
const services = await createAgentSessionServices({ cwd });
|
|
805
|
-
return {
|
|
806
|
-
...(await createAgentSessionFromServices({
|
|
807
|
-
services,
|
|
808
|
-
sessionManager,
|
|
809
|
-
sessionStartEvent,
|
|
810
|
-
})),
|
|
811
|
-
services,
|
|
812
|
-
diagnostics: services.diagnostics,
|
|
813
|
-
};
|
|
814
|
-
};
|
|
815
|
-
|
|
816
|
-
const runtime = await createAgentSessionRuntime(createRuntime, {
|
|
817
|
-
cwd: process.cwd(),
|
|
818
|
-
agentDir: getAgentDir(),
|
|
819
|
-
sessionManager: SessionManager.create(process.cwd()),
|
|
820
|
-
});
|
|
821
|
-
|
|
822
|
-
// Replace the active session with a fresh one
|
|
823
|
-
await runtime.newSession();
|
|
824
|
-
|
|
825
|
-
// Replace the active session with another saved session
|
|
826
|
-
await runtime.switchSession("/path/to/session.jsonl");
|
|
827
|
-
|
|
828
|
-
// Replace the active session with a fork from a specific user entry
|
|
829
|
-
await runtime.fork("entry-id");
|
|
830
|
-
|
|
831
|
-
// Clone the active path through a specific entry
|
|
832
|
-
await runtime.fork("entry-id", { position: "at" });
|
|
833
|
-
```
|
|
834
|
-
|
|
835
|
-
**SessionManager tree API:**
|
|
836
|
-
|
|
837
|
-
```typescript
|
|
838
|
-
const sm = SessionManager.open("/path/to/session.jsonl");
|
|
839
|
-
|
|
840
|
-
// Session listing
|
|
841
|
-
const currentProjectSessions = await SessionManager.list(process.cwd());
|
|
842
|
-
const allSessions = await SessionManager.listAll(process.cwd());
|
|
843
|
-
|
|
844
|
-
// Tree traversal
|
|
845
|
-
const entries = sm.getEntries(); // All entries (excludes header)
|
|
846
|
-
const tree = sm.getTree(); // Full tree structure
|
|
847
|
-
const path = sm.getPath(); // Path from root to current leaf
|
|
848
|
-
const leaf = sm.getLeafEntry(); // Current leaf entry
|
|
849
|
-
const entry = sm.getEntry(id); // Get entry by ID
|
|
850
|
-
const children = sm.getChildren(id); // Direct children of entry
|
|
851
|
-
|
|
852
|
-
// Labels
|
|
853
|
-
const label = sm.getLabel(id); // Get label for entry
|
|
854
|
-
sm.appendLabelChange(id, "checkpoint"); // Set label
|
|
855
|
-
|
|
856
|
-
// Branching
|
|
857
|
-
sm.branch(entryId); // Move leaf to earlier entry
|
|
858
|
-
sm.branchWithSummary(id, "Summary..."); // Branch with context summary
|
|
859
|
-
sm.createBranchedSession(leafId); // Extract path to new file
|
|
860
|
-
```
|
|
861
|
-
|
|
862
|
-
> See [examples/sdk/11-sessions.ts](../examples/sdk/11-sessions.ts) and [Session Format](session-format.md)
|
|
863
|
-
|
|
864
|
-
### Settings Management
|
|
865
|
-
|
|
866
|
-
```typescript
|
|
867
|
-
import { createAgentSession, SettingsManager, SessionManager } from "@punch-bot/cli";
|
|
868
|
-
|
|
869
|
-
// Default: loads from files (global + project merged)
|
|
870
|
-
const { session } = await createAgentSession({
|
|
871
|
-
settingsManager: SettingsManager.create(),
|
|
872
|
-
});
|
|
873
|
-
|
|
874
|
-
// With overrides
|
|
875
|
-
const settingsManager = SettingsManager.create();
|
|
876
|
-
settingsManager.applyOverrides({
|
|
877
|
-
compaction: { enabled: false },
|
|
878
|
-
retry: { enabled: true, maxRetries: 5 },
|
|
879
|
-
});
|
|
880
|
-
const { session } = await createAgentSession({ settingsManager });
|
|
881
|
-
|
|
882
|
-
// In-memory (no file I/O, for testing)
|
|
883
|
-
const { session } = await createAgentSession({
|
|
884
|
-
settingsManager: SettingsManager.inMemory({ compaction: { enabled: false } }),
|
|
885
48
|
sessionManager: SessionManager.inMemory(),
|
|
886
49
|
});
|
|
887
|
-
|
|
888
|
-
// Custom directories
|
|
889
|
-
const { session } = await createAgentSession({
|
|
890
|
-
settingsManager: SettingsManager.create("/custom/cwd", "/custom/agent"),
|
|
891
|
-
});
|
|
892
50
|
```
|
|
893
51
|
|
|
894
|
-
|
|
895
|
-
- `SettingsManager.create(cwd?, agentDir?)` - Load from files
|
|
896
|
-
- `SettingsManager.inMemory(settings?)` - No file I/O
|
|
897
|
-
|
|
898
|
-
**Project-specific settings:**
|
|
52
|
+
See the checked [sessions example](../examples/sdk/11-sessions.ts) for creating, opening, continuing, listing, and forking sessions. [Session File Format](session-format.md) defines the persisted JSONL contract, and [Message Types](message-types.md) defines transcript values. For exact methods and signatures, use the exported TypeScript declarations or [`session-manager.ts`](../src/core/session-manager.ts).
|
|
899
53
|
|
|
900
|
-
|
|
901
|
-
1. Global: `~/.pi/agent/settings.json`
|
|
902
|
-
2. Project: `<cwd>/.pi/settings.json`
|
|
54
|
+
`cwd` selects the workspace used for project resource discovery, context files, session grouping, and built-in tool paths. Pass it explicitly when the target differs from `process.cwd()`.
|
|
903
55
|
|
|
904
|
-
|
|
56
|
+
`session.dispose()` aborts active work, invalidates extension contexts, disconnects from the agent, and removes event listeners. Call it when the session is no longer needed.
|
|
905
57
|
|
|
906
|
-
|
|
58
|
+
`AgentSessionRuntime` adds `newSession()`, `switchSession()`, `fork()`, and `importFromJsonl()`. Each operation replaces the active `AgentSession` and recreates services for the target working directory.
|
|
907
59
|
|
|
908
|
-
|
|
909
|
-
- Setters enqueue persistence writes asynchronously.
|
|
910
|
-
- Call `await settingsManager.flush()` when you need a durability boundary (for example, before process exit or before asserting file contents in tests).
|
|
911
|
-
- `SettingsManager` does not print settings I/O errors. Use `settingsManager.drainErrors()` and report them in your app layer.
|
|
912
|
-
|
|
913
|
-
> See [examples/sdk/10-settings.ts](../examples/sdk/10-settings.ts)
|
|
914
|
-
|
|
915
|
-
## ResourceLoader
|
|
916
|
-
|
|
917
|
-
Use `DefaultResourceLoader` to discover extensions, skills, prompts, themes, and context files.
|
|
918
|
-
|
|
919
|
-
```typescript
|
|
920
|
-
import {
|
|
921
|
-
DefaultResourceLoader,
|
|
922
|
-
getAgentDir,
|
|
923
|
-
} from "@punch-bot/cli";
|
|
60
|
+
After a runtime replacement, subscriptions belong to the old `AgentSession` and must be rebound. See the [session runtime example](../examples/sdk/13-session-runtime.ts).
|
|
924
61
|
|
|
925
|
-
|
|
926
|
-
cwd,
|
|
927
|
-
agentDir: getAgentDir(),
|
|
928
|
-
});
|
|
929
|
-
await loader.reload();
|
|
62
|
+
## Prompting
|
|
930
63
|
|
|
931
|
-
|
|
932
|
-
const skills = loader.getSkills();
|
|
933
|
-
const prompts = loader.getPrompts();
|
|
934
|
-
const themes = loader.getThemes();
|
|
935
|
-
const contextFiles = loader.getAgentsFiles().agentsFiles;
|
|
936
|
-
```
|
|
64
|
+
`prompt()` handles extension commands and expands file-based prompt templates before ordinary user messages enter the agent. For an accepted agent run, it resolves after the run finishes, including automatic retries.
|
|
937
65
|
|
|
938
|
-
|
|
66
|
+
A prompt sent while the session is already streaming must specify whether it should steer the current run or follow it. Calling `prompt()` without that choice rejects rather than guessing.
|
|
939
67
|
|
|
940
|
-
`
|
|
68
|
+
A steering message enters after the current assistant turn and its tool calls. A follow-up enters after the current run finishes its pending work. `steer()` and `followUp()` expose those behaviors directly and return `"queued"` if the input was queued (including after an extension transformed it), or `"handled"` if an extension consumed it.
|
|
941
69
|
|
|
942
|
-
|
|
943
|
-
interface CreateAgentSessionResult {
|
|
944
|
-
// The session
|
|
945
|
-
session: AgentSession;
|
|
946
|
-
|
|
947
|
-
// Extensions result (for runner setup)
|
|
948
|
-
extensionsResult: LoadExtensionsResult;
|
|
949
|
-
|
|
950
|
-
// Warning if session model couldn't be restored
|
|
951
|
-
modelFallbackMessage?: string;
|
|
952
|
-
}
|
|
70
|
+
`abort()` stops the active operation and waits for the session to become idle. `waitForIdle()` waits without aborting it.
|
|
953
71
|
|
|
954
|
-
|
|
955
|
-
extensions: Extension[];
|
|
956
|
-
errors: Array<{ path: string; error: string }>;
|
|
957
|
-
runtime: ExtensionRuntime;
|
|
958
|
-
}
|
|
959
|
-
```
|
|
72
|
+
## Subscribing to events
|
|
960
73
|
|
|
961
|
-
|
|
74
|
+
Subscribe before prompting when the host needs streamed output:
|
|
962
75
|
|
|
963
76
|
```typescript
|
|
964
|
-
|
|
965
|
-
import { Type } from "typebox";
|
|
966
|
-
import {
|
|
967
|
-
createAgentSession,
|
|
968
|
-
DefaultResourceLoader,
|
|
969
|
-
defineTool,
|
|
970
|
-
ModelRuntime,
|
|
971
|
-
SessionManager,
|
|
972
|
-
SettingsManager,
|
|
973
|
-
} from "@punch-bot/cli";
|
|
974
|
-
|
|
975
|
-
const modelRuntime = await ModelRuntime.create({
|
|
976
|
-
authPath: "/custom/agent/auth.json",
|
|
977
|
-
modelsPath: "/custom/agent/models.json",
|
|
978
|
-
});
|
|
979
|
-
if (process.env.MY_KEY) {
|
|
980
|
-
await modelRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY);
|
|
981
|
-
}
|
|
982
|
-
|
|
983
|
-
// Inline tool
|
|
984
|
-
const statusTool = defineTool({
|
|
985
|
-
name: "status",
|
|
986
|
-
label: "Status",
|
|
987
|
-
description: "Get system status",
|
|
988
|
-
parameters: Type.Object({}),
|
|
989
|
-
execute: async () => ({
|
|
990
|
-
content: [{ type: "text", text: `Uptime: ${process.uptime()}s` }],
|
|
991
|
-
details: {},
|
|
992
|
-
}),
|
|
993
|
-
});
|
|
994
|
-
|
|
995
|
-
const model = getModel("anthropic", "claude-opus-4-5");
|
|
996
|
-
if (!model) throw new Error("Model not found");
|
|
997
|
-
|
|
998
|
-
// In-memory settings with overrides
|
|
999
|
-
const settingsManager = SettingsManager.inMemory({
|
|
1000
|
-
compaction: { enabled: false },
|
|
1001
|
-
retry: { enabled: true, maxRetries: 2 },
|
|
1002
|
-
});
|
|
1003
|
-
|
|
1004
|
-
const loader = new DefaultResourceLoader({
|
|
1005
|
-
cwd: process.cwd(),
|
|
1006
|
-
agentDir: "/custom/agent",
|
|
1007
|
-
settingsManager,
|
|
1008
|
-
systemPromptOverride: () => "You are a minimal assistant. Be concise.",
|
|
1009
|
-
});
|
|
1010
|
-
await loader.reload();
|
|
1011
|
-
|
|
1012
|
-
const { session } = await createAgentSession({
|
|
1013
|
-
cwd: process.cwd(),
|
|
1014
|
-
agentDir: "/custom/agent",
|
|
1015
|
-
|
|
1016
|
-
model,
|
|
1017
|
-
thinkingLevel: "off",
|
|
1018
|
-
modelRuntime,
|
|
1019
|
-
|
|
1020
|
-
tools: ["read", "bash", "status"],
|
|
1021
|
-
customTools: [statusTool],
|
|
1022
|
-
resourceLoader: loader,
|
|
1023
|
-
|
|
1024
|
-
sessionManager: SessionManager.inMemory(),
|
|
1025
|
-
settingsManager,
|
|
1026
|
-
});
|
|
1027
|
-
|
|
1028
|
-
session.subscribe((event) => {
|
|
77
|
+
const unsubscribe = session.subscribe((event) => {
|
|
1029
78
|
if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
|
|
1030
79
|
process.stdout.write(event.assistantMessageEvent.delta);
|
|
1031
80
|
}
|
|
1032
81
|
});
|
|
1033
82
|
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
The SDK exports run mode utilities for building custom interfaces on top of `createAgentSession()`:
|
|
1040
|
-
|
|
1041
|
-
### InteractiveMode
|
|
1042
|
-
|
|
1043
|
-
Full TUI interactive mode with editor, chat history, and all built-in commands:
|
|
1044
|
-
|
|
1045
|
-
```typescript
|
|
1046
|
-
import {
|
|
1047
|
-
type CreateAgentSessionRuntimeFactory,
|
|
1048
|
-
createAgentSessionFromServices,
|
|
1049
|
-
createAgentSessionRuntime,
|
|
1050
|
-
createAgentSessionServices,
|
|
1051
|
-
getAgentDir,
|
|
1052
|
-
InteractiveMode,
|
|
1053
|
-
SessionManager,
|
|
1054
|
-
} from "@punch-bot/cli";
|
|
1055
|
-
|
|
1056
|
-
const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
|
|
1057
|
-
const services = await createAgentSessionServices({ cwd });
|
|
1058
|
-
return {
|
|
1059
|
-
...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
|
|
1060
|
-
services,
|
|
1061
|
-
diagnostics: services.diagnostics,
|
|
1062
|
-
};
|
|
1063
|
-
};
|
|
1064
|
-
const runtime = await createAgentSessionRuntime(createRuntime, {
|
|
1065
|
-
cwd: process.cwd(),
|
|
1066
|
-
agentDir: getAgentDir(),
|
|
1067
|
-
sessionManager: SessionManager.create(process.cwd()),
|
|
1068
|
-
});
|
|
1069
|
-
|
|
1070
|
-
const mode = new InteractiveMode(runtime, {
|
|
1071
|
-
migratedProviders: [],
|
|
1072
|
-
modelFallbackMessage: undefined,
|
|
1073
|
-
initialMessage: "Hello",
|
|
1074
|
-
initialImages: [],
|
|
1075
|
-
initialMessages: [],
|
|
1076
|
-
});
|
|
1077
|
-
|
|
1078
|
-
await mode.run();
|
|
1079
|
-
```
|
|
1080
|
-
|
|
1081
|
-
### runPrintMode
|
|
1082
|
-
|
|
1083
|
-
Single-shot mode: send prompts, output result, exit:
|
|
1084
|
-
|
|
1085
|
-
```typescript
|
|
1086
|
-
import {
|
|
1087
|
-
type CreateAgentSessionRuntimeFactory,
|
|
1088
|
-
createAgentSessionFromServices,
|
|
1089
|
-
createAgentSessionRuntime,
|
|
1090
|
-
createAgentSessionServices,
|
|
1091
|
-
getAgentDir,
|
|
1092
|
-
runPrintMode,
|
|
1093
|
-
SessionManager,
|
|
1094
|
-
} from "@punch-bot/cli";
|
|
1095
|
-
|
|
1096
|
-
const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
|
|
1097
|
-
const services = await createAgentSessionServices({ cwd });
|
|
1098
|
-
return {
|
|
1099
|
-
...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
|
|
1100
|
-
services,
|
|
1101
|
-
diagnostics: services.diagnostics,
|
|
1102
|
-
};
|
|
1103
|
-
};
|
|
1104
|
-
const runtime = await createAgentSessionRuntime(createRuntime, {
|
|
1105
|
-
cwd: process.cwd(),
|
|
1106
|
-
agentDir: getAgentDir(),
|
|
1107
|
-
sessionManager: SessionManager.create(process.cwd()),
|
|
1108
|
-
});
|
|
1109
|
-
|
|
1110
|
-
await runPrintMode(runtime, {
|
|
1111
|
-
mode: "text",
|
|
1112
|
-
initialMessage: "Hello",
|
|
1113
|
-
initialImages: [],
|
|
1114
|
-
messages: ["Follow up"],
|
|
1115
|
-
});
|
|
83
|
+
try {
|
|
84
|
+
await session.prompt("Explain this repository");
|
|
85
|
+
} finally {
|
|
86
|
+
unsubscribe();
|
|
87
|
+
}
|
|
1116
88
|
```
|
|
1117
89
|
|
|
1118
|
-
|
|
90
|
+
Session events report message updates, tool execution, queues, compaction, retries, and run lifecycle changes.
|
|
1119
91
|
|
|
1120
|
-
|
|
92
|
+
`message_end` contains the authoritative completed message. `agent_end` marks the end of one low-level agent run, but automatic recovery or queued work can still follow.
|
|
1121
93
|
|
|
1122
|
-
|
|
1123
|
-
import {
|
|
1124
|
-
type CreateAgentSessionRuntimeFactory,
|
|
1125
|
-
createAgentSessionFromServices,
|
|
1126
|
-
createAgentSessionRuntime,
|
|
1127
|
-
createAgentSessionServices,
|
|
1128
|
-
getAgentDir,
|
|
1129
|
-
runRpcMode,
|
|
1130
|
-
SessionManager,
|
|
1131
|
-
} from "@punch-bot/cli";
|
|
94
|
+
Use `agent_settled` when the host needs to know that Pi will not continue automatically.
|
|
1132
95
|
|
|
1133
|
-
|
|
1134
|
-
const services = await createAgentSessionServices({ cwd });
|
|
1135
|
-
return {
|
|
1136
|
-
...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
|
|
1137
|
-
services,
|
|
1138
|
-
diagnostics: services.diagnostics,
|
|
1139
|
-
};
|
|
1140
|
-
};
|
|
1141
|
-
const runtime = await createAgentSessionRuntime(createRuntime, {
|
|
1142
|
-
cwd: process.cwd(),
|
|
1143
|
-
agentDir: getAgentDir(),
|
|
1144
|
-
sessionManager: SessionManager.create(process.cwd()),
|
|
1145
|
-
});
|
|
96
|
+
## Configuring a session
|
|
1146
97
|
|
|
1147
|
-
|
|
1148
|
-
```
|
|
98
|
+
Without overrides, the factory creates a `ModelRuntime`, file-backed `SettingsManager`, persistent `SessionManager`, `DefaultResourceLoader`, and the configured default tools.
|
|
1149
99
|
|
|
1150
|
-
|
|
100
|
+
Each boundary can be supplied explicitly:
|
|
1151
101
|
|
|
1152
|
-
|
|
102
|
+
- `modelRuntime`, `model`, `thinkingLevel`, and `scopedModels` control model access and selection.
|
|
103
|
+
- `settingsManager` supplies merged settings or an in-memory configuration.
|
|
104
|
+
- `sessionManager` supplies persistent or in-memory conversation history.
|
|
105
|
+
- `resourceLoader` supplies extensions, skills, prompt templates, themes, and context files.
|
|
106
|
+
- `tools`, `noTools`, `excludeTools`, and `customTools` control the active tool set.
|
|
1153
107
|
|
|
1154
|
-
|
|
108
|
+
Use `DefaultResourceLoader` when you want standard discovery with selected overrides. Supply a custom `ResourceLoader` when the host owns resource storage and discovery completely.
|
|
1155
109
|
|
|
1156
|
-
|
|
1157
|
-
pi --mode rpc --no-session
|
|
1158
|
-
```
|
|
110
|
+
<a id="inlineextension"></a>
|
|
1159
111
|
|
|
1160
|
-
|
|
112
|
+
Inline extension factories can be supplied through `DefaultResourceLoader`. Give one an `InlineExtension` name only when it needs a stable name in diagnostics and startup output. A named inline extension with `replaceable: true` is left out when another extension registers a tool, command, or flag with a name it registers during loading, instead of both loading with a conflict. The CLI's built-in codemode, tool search, and MCP extensions are replaceable. A named entry with `builtin: true` is not an inline extension: it supplies the code of the `builtin:<name>` extension, which loads like a configured extension file. It loads by default, is listed in `pi config`, and is disabled by `-builtin:<name>` in the `extensions` setting or by `noExtensions`; `additionalExtensionPaths: ["builtin:<name>"]` loads it explicitly. It loads after project trust is resolved, so it cannot handle `project_trust`. The CLI's built-in extensions use it.
|
|
1161
113
|
|
|
1162
|
-
|
|
1163
|
-
- You want type safety
|
|
1164
|
-
- You're in the same Node.js process
|
|
1165
|
-
- You need direct access to agent state
|
|
1166
|
-
- You want to customize tools/extensions programmatically
|
|
114
|
+
<a id="codemode-mcp"></a>
|
|
1167
115
|
|
|
1168
|
-
|
|
1169
|
-
- You're integrating from another language
|
|
1170
|
-
- You want process isolation
|
|
1171
|
-
- You're building a language-agnostic client
|
|
116
|
+
The CLI loads `codemode`, `tool_search`, and MCP as built-in extensions. SDK sessions do not; add `createCodemodeExtension()`, `createToolSearchExtension()`, and `createMcpExtension()` to the `extensionFactories` of `DefaultResourceLoader`. `codemode` and `tool_search` are registered inactive: enable them through the `defaultTools` setting (`["+codemode", "+tool_search"]` keeps the other default tools), or let the MCP extension activate them: `codemode` for servers with `codemode` exposure, `tool_search` for servers with `deferred` exposure. The MCP extension connects its servers on `session_start`, so call `session.bindExtensions()`. See [Codemode and MCP](../examples/sdk/14-codemode-mcp.ts).
|
|
1172
117
|
|
|
1173
|
-
|
|
118
|
+
See the focused examples for [models](../examples/sdk/02-custom-model.ts), [tools](../examples/sdk/05-tools.ts), [extensions](../examples/sdk/06-extensions.ts), and [full control](../examples/sdk/12-full-control.ts).
|
|
1174
119
|
|
|
1175
|
-
|
|
120
|
+
## Examples
|
|
1176
121
|
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
|
|
1180
|
-
|
|
1181
|
-
|
|
122
|
+
| Example | Purpose |
|
|
123
|
+
|---|---|
|
|
124
|
+
| [Minimal](../examples/sdk/01-minimal.ts) | Create, prompt, observe, and dispose a session |
|
|
125
|
+
| [Custom model](../examples/sdk/02-custom-model.ts) | Select a model and thinking level |
|
|
126
|
+
| [System prompt](../examples/sdk/03-custom-prompt.ts) | Replace or append to the system prompt |
|
|
127
|
+
| [Skills](../examples/sdk/04-skills.ts) | Discover, filter, and add skills |
|
|
128
|
+
| [Tools](../examples/sdk/05-tools.ts) | Select built-in tools and their working directory |
|
|
129
|
+
| [Extensions](../examples/sdk/06-extensions.ts) | Load file-based and inline extensions |
|
|
130
|
+
| [Context files](../examples/sdk/07-context-files.ts) | Add or replace project instructions |
|
|
131
|
+
| [Prompt templates](../examples/sdk/08-prompt-templates.ts) | Add file-style prompt templates |
|
|
132
|
+
| [Credentials](../examples/sdk/09-api-keys-and-oauth.ts) | Configure credential and model storage |
|
|
133
|
+
| [Settings](../examples/sdk/10-settings.ts) | Supply file-backed or in-memory settings |
|
|
134
|
+
| [Sessions](../examples/sdk/11-sessions.ts) | Control session persistence and restoration |
|
|
135
|
+
| [Full control](../examples/sdk/12-full-control.ts) | Replace default discovery and state services |
|
|
136
|
+
| [Session runtime](../examples/sdk/13-session-runtime.ts) | Replace the active session safely |
|
|
137
|
+
| [Codemode and MCP](../examples/sdk/14-codemode-mcp.ts) | Add the `codemode`, `tool_search`, and MCP extensions |
|
|
1182
138
|
|
|
1183
|
-
|
|
1184
|
-
ModelRuntime // implements pi-ai Models and owns credential storage
|
|
1185
|
-
ModelRegistry // synchronous extension compatibility facade
|
|
1186
|
-
CredentialSynchronizationError
|
|
1187
|
-
resolveCliModel
|
|
1188
|
-
resolveModelScopeWithDiagnostics
|
|
139
|
+
<a id="exports"></a>
|
|
1189
140
|
|
|
1190
|
-
|
|
1191
|
-
DefaultResourceLoader
|
|
1192
|
-
type ResourceLoader
|
|
1193
|
-
createEventBus
|
|
1194
|
-
|
|
1195
|
-
// Constants and helpers
|
|
1196
|
-
CONFIG_DIR_NAME
|
|
1197
|
-
defineTool
|
|
1198
|
-
getAgentDir
|
|
1199
|
-
getPackageDir
|
|
1200
|
-
getReadmePath
|
|
1201
|
-
getDocsPath
|
|
1202
|
-
getExamplesPath
|
|
1203
|
-
|
|
1204
|
-
// Session management
|
|
1205
|
-
SessionManager
|
|
1206
|
-
SettingsManager
|
|
1207
|
-
|
|
1208
|
-
// Tool factories
|
|
1209
|
-
createCodingTools
|
|
1210
|
-
createReadOnlyTools
|
|
1211
|
-
createReadTool, createBashTool, createPowerShellTool, createEditTool, createWriteTool
|
|
1212
|
-
createGrepTool, createFindTool, createLsTool
|
|
1213
|
-
|
|
1214
|
-
// Types
|
|
1215
|
-
type CreateAgentSessionOptions
|
|
1216
|
-
type CreateAgentSessionResult
|
|
1217
|
-
type ExtensionFactory
|
|
1218
|
-
type InlineExtension
|
|
1219
|
-
type ExtensionAPI
|
|
1220
|
-
type ToolDefinition
|
|
1221
|
-
type Skill
|
|
1222
|
-
type PromptTemplate
|
|
1223
|
-
type Tool
|
|
1224
|
-
```
|
|
141
|
+
## Resources
|
|
1225
142
|
|
|
1226
|
-
|
|
143
|
+
- [Choose a Model](models.md) covers model selection and compatible endpoints; [Providers](providers.md) covers credentials and provider-specific setup.
|
|
144
|
+
- [Configuration](configuration.md) explains normal discovery and settings; [Settings](settings.md) lists every setting.
|
|
145
|
+
- [Sessions and Context](sessions.md) explains session behavior; [Session Format](session-format.md) defines persisted entries; [Message Types](message-types.md) defines shared transcript values.
|
|
146
|
+
- [Extensions](extensions.md), [Skills](skills.md), and [Prompt Templates](prompt-templates.md) document resources supplied through a `ResourceLoader`.
|
|
147
|
+
- [CLI Integration](cli-integration.md) covers print, JSON, and RPC alternatives to an in-process SDK integration.
|