@agimon-ai/po-codemode 0.0.1-alpha.14 → 0.0.1-alpha.141

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/README.md CHANGED
@@ -1,94 +1,46 @@
1
1
  # @agimon-ai/po-codemode
2
2
 
3
- Code mode for Po sessions: discover and exec over namespaces other packages contribute
3
+ Discover typed capabilities contributed by other Po packages, then call them from a TypeScript script with `exec`.
4
4
 
5
- This package is a composable [Po](https://www.npmjs.com/package/@agimon-ai/po) subsystem. Use it through native server composition in the distribution.
6
-
7
- ## Requirements
8
-
9
- - Node.js 24 or newer
10
- - `@earendil-works/pi-coding-agent` 1.3.0
11
-
12
- ## Install
13
-
14
- ```bash
15
- pnpm add @agimon-ai/po-codemode
16
- ```
17
-
18
- The package declares poServer metadata for native server discovery. Include it through normal profile and domain composition.
5
+ Select this package through Po's package composition. It requires Node.js 24 or newer; optional Pi peer compatibility is declared in [package.json](package.json).
19
6
 
20
7
  ## Use
21
8
 
22
- Call `discover({})` to list the session's contributed namespaces and reusable scripts. Use `exec` to run a TypeScript async function body against them.
23
-
24
- ## Package behavior
25
-
26
- Call `discover({ namespace: 'browser' })` for current types, then `exec({ code: 'return await browser.snapshot({});' })`. Namespace plugins supply their own `codemode-how-to-<plugin>` guides. Their summaries and the base `how-to-codemode` guide stay in the system prompt, outside skill search; `load_skill` still reads their full instructions by exact name.
27
-
28
- ### npm imports
9
+ Call `discover({})` to list available namespaces and reusable scripts. Pass a namespace name to read its current TypeScript declarations, then use `exec` to call its methods. A namespace is available only when its owning package and required services are active.
29
10
 
30
- On Node hosts, `await import('npm:is-number@7')` auto-installs through upm and returns the real module namespace. Registry names, scopes, versions, ranges, tags and subpaths are supported. The shared store uses the existing two-day release-age policy (exact and locked versions bypass it); lifecycle scripts are skipped. First installs may need a larger exec `timeoutMs`.
11
+ Namespace summaries and the base `how-to-codemode` guide stay in the system prompt. Load the owning package's `codemode-how-to-<plugin>` skill for workflow guidance. Signatures come from `discover`, not a copied README example.
31
12
 
32
- Packages run with full Node authority. Native code is not preemptible, package resources are not automatically closed, and cancellation cannot stop an install already in progress. `new` works on imported constructors; subclassing and `instanceof` are unsupported. Edge hosts cannot import. Script globals still omit `fetch`, `require` and `process`.
13
+ Scripts are saved under the session's temporary directory. Import a listed script with `await (await import(specifier))(args)`. `exec_background` runs longer work asynchronously; `exec_cancel` requests cancellation. Neither makes the work durable beyond its session.
33
14
 
34
- ### Short Bash commands
15
+ ## Imports and execution limits
35
16
 
36
- `shell.bash({ command, timeoutMs? })` returns `{ stdout, stderr, exitCode }` for code-side post-processing. It runs in the session cwd with its admitted environment. Nonzero exits are returned; startup failures, timeout and cancellation reject. The deadline defaults to 10 seconds (maximum 120 seconds) and the command is cancelled when exec ends. Each output stream is capped at 32768 characters with a `[truncated]` marker.
17
+ On Node hosts, `await import('npm:is-number@7')` installs through Po's package manager and returns the module namespace. Names, scopes, versions, ranges, tags and subpaths are supported. The store applies its two-day release-age policy, with exact and locked versions exempt; lifecycle scripts are skipped. A first install may need a larger `timeoutMs`.
37
18
 
38
- This is foreground-only execution, not Runner supervision: no background option, interactive terminal, Runner IDs or persistent logs. The standalone Runner `bash` tool remains visible for those workflows. See [shell guidance](./src/prompts/codemode-how-to-shell/SKILL.md).
19
+ Imported packages run with full Node authority, not OS isolation. Native code is not preemptible, package resources are not automatically closed, and cancellation cannot stop an installation already in progress. Constructors work with `new`; subclassing and `instanceof` are unsupported. Edge hosts cannot import npm packages. Script globals omit `fetch`, `require` and `process`.
39
20
 
40
- ### LLM transformations
21
+ Where provided, `node:fs` and `node:fs/promises` imports use the session's injected filesystem. They are not permission to import arbitrary Node built-ins.
41
22
 
42
- `llm.complete({ prompt, input? })` returns `{ text, model }`; `llm.json({ prompt, input?, schema })` returns `{ value, model }`. Calls are stateless, use no session history, and count toward session usage. JSON results require one private `return_result` call and local schema validation; tool choice is prompt-directed.
23
+ ## Short shell commands
43
24
 
44
- Set the optional `llmModel: provider/id` in the `@agimon-ai/po-codemode` package configuration to choose a default. A per-call `model` wins, otherwise the current session model is used. Limits per exec are 8 calls and 2 concurrent calls, with 64 KiB input per call and 1024 default / 4096 maximum output tokens. There are no retries. See [LLM guidance](./src/prompts/codemode-how-to-llm/SKILL.md) for pipelines and schema constraints.
25
+ `shell.bash({ command, timeoutMs? })` returns `{ stdout, stderr, exitCode }` in the session's working directory and admitted environment. Nonzero exits are values; startup failure, timeout and cancellation reject. The default deadline is 10 seconds, with a 120-second maximum. Each stream is capped at 32,768 characters, and the command is cancelled when exec ends.
45
26
 
46
- ## How-to guide
27
+ Use the standalone Runner `bash` tool for supervised background work, interactive input, or persistent command logs. See the [shell guide](src/prompts/codemode-how-to-shell/SKILL.md).
47
28
 
48
- The published package includes `llms.txt` and `src/prompts/how-to-codemode/SKILL.md`. Link additional prompts from `llms.txt` and declare them through named `resource/*.server.ts` routes using `defineResource`. Server lifecycle registration owns their disposal. Publish prompts under `src/prompts`, never export Markdown or copy it into `dist`.
29
+ ## Model transformations
49
30
 
50
- ## Public API
31
+ `llm.complete({ prompt, input? })` returns text and the selected model. `llm.json({ prompt, input?, schema })` returns a locally validated value and the model. Calls are stateless, receive no conversation history, and count toward session usage.
51
32
 
52
- ```ts
53
- import { createCodemodeRegistry, createCodemodeTools } from '@agimon-ai/po-codemode';
54
- ```
33
+ The package's optional `llmModel: provider/id` setting supplies a default; a per-call model wins, otherwise the active session model is used. Each exec allows eight calls, two concurrent calls, and 64 KiB input per call. Output defaults to 1,024 tokens with a 4,096 maximum. There are no retries. See the [LLM guide](src/prompts/codemode-how-to-llm/SKILL.md).
55
34
 
56
- The native server entry is also available at:
35
+ ## Host integration
57
36
 
58
- ```text
59
- @agimon-ai/po-codemode/extensions/server
60
- ```
37
+ The root exports `createCodemodeRegistry` and `createCodemodeTools`. The native server entry is `@agimon-ai/po-codemode/extensions/server`. The package publishes its guides through `llms.txt` and named resource routes.
61
38
 
62
- The build generates host entrypoints in `generated/` from named `src/extensions` routes. Pure re-export modules in `src/exports` expose selected public capabilities. Keep typed authoring helpers in a dedicated subpath with no host/runtime imports so repository modules can bundle them cheaply.
63
-
64
- ## Structure and lifecycle
65
-
66
- - `extensions/`: path-routed host contracts. Every scanned file default-exports one typed `define*` declaration.
67
- - `services/{serviceName}/`: package logic, with `index.ts` and `type.ts`.
68
- - `models/`: host-neutral state and transitions.
69
- - `constants/`, `schemas/`, and `types/`: shared metadata, validation, and contracts.
70
- - Private `_lib/` and `_components/` folders beside routes hold surface-private implementation and are not scanned.
71
-
72
- Use scoped `root.server.ts` `defineRoot` factories for shared dependencies, Cordis services and lifecycle. Put each tool, command, hook, method, API, resource, and presentation contribution in its own named routed file. Do not use catch-all entries, named exports in routes, or freeform route implementation.
73
-
74
- Give each event one owner. Server plugins own session hooks and shared runtime services.
75
-
76
- The lifecycle is construct, register, `onStart`, run, `onStop`, unregister, `onDispose`. All hooks are optional and receive one typed context. The helper awaits startup before readiness. Shutdown aborts the context signal, stops work, removes registrations in reverse order, and performs final cleanup. Failed startup awaits rollback. Optional provider replacement rebinds contributions without restarting the plugin. Minor-mode actions are independent of mounting.
77
-
78
- Factories construct state; `onStart` begins external work. `onStop` runs when the start stage was reached, including a failed `onStart`. Use `onDispose` only for remaining instance resources. Do not add empty hooks or manual registration cleanup.
39
+ For extension layout and lifecycle rules, see [Po architecture](https://github.com/AgiFlow/po/blob/main/docs/architecture.md#extensions), rather than maintaining a second copy here.
79
40
 
80
41
  ## Development
81
42
 
82
- ```bash
83
- pnpm build
84
- pnpm typecheck
85
- pnpm test
86
- pnpm lint
87
- pnpm exec vibe-lint check .
88
- npm pack --dry-run
89
- ```
90
-
91
- Maintained by [Agimon](https://agimon.ai/about).
43
+ Run this package's `build`, `typecheck`, `test`, and `lint` scripts from its directory.
92
44
 
93
45
  ## License
94
46
 
@@ -2,12 +2,29 @@ Object.defineProperties(exports, {
2
2
  __esModule: { value: true },
3
3
  [Symbol.toStringTag]: { value: "Module" }
4
4
  });
5
+ let _agimon_ai_po_core_apiContracts = require("@agimon-ai/po-core/apiContracts");
6
+ let typebox = require("typebox");
5
7
  //#region src/schemas/apiContracts.ts
6
- /** This server plugin contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
7
- const apiContracts = (0, require("@agimon-ai/po-core/apiContracts").defineApiContract)({
8
+ const BackgroundScriptsPayloadSchema = typebox.Type.Object({ scripts: typebox.Type.Array(typebox.Type.Object({
9
+ id: typebox.Type.String(),
10
+ label: typebox.Type.String(),
11
+ startedAt: typebox.Type.String(),
12
+ status: typebox.Type.Union([typebox.Type.Literal("running"), typebox.Type.Literal("reporting")])
13
+ })) });
14
+ /** Agent tools and commands carry no HTTP surface; the page reads running background scripts from one hub channel. */
15
+ const apiContracts = (0, _agimon_ai_po_core_apiContracts.defineApiContract)({
8
16
  version: 1,
9
17
  http: [],
10
- sockets: [],
18
+ sockets: ["host", "workspace"].map((scope) => ({
19
+ id: "codemode.background.channel",
20
+ scope,
21
+ service: "po.hub",
22
+ member: "codemode_background",
23
+ kind: "channel",
24
+ direction: "server-to-client",
25
+ description: "The session's running background code-mode scripts, in the hub frame payload property.",
26
+ input: BackgroundScriptsPayloadSchema
27
+ })),
11
28
  dynamic: []
12
29
  });
13
30
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"apiContracts.cjs","names":["defineApiContract"],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/po-core/apiContracts';\n\n/** This server plugin contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;;;;AAGA,MAAa,gBAAA,4CAAeA,CAAAA,CAAAA,kBAAAA,CAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}
1
+ {"version":3,"file":"apiContracts.cjs","names":["Type","defineApiContract"],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/po-core/apiContracts';\nimport { Type } from 'typebox';\n\nexport const BackgroundScriptsPayloadSchema = Type.Object({\n scripts: Type.Array(\n Type.Object({\n id: Type.String(),\n label: Type.String(),\n startedAt: Type.String(),\n status: Type.Union([Type.Literal('running'), Type.Literal('reporting')]),\n }),\n ),\n});\n\n/** Agent tools and commands carry no HTTP surface; the page reads running background scripts from one hub channel. */\nexport const apiContracts = defineApiContract({\n version: 1,\n http: [],\n sockets: (['host', 'workspace'] as const).map((scope) => ({\n id: 'codemode.background.channel',\n scope,\n service: 'po.hub',\n member: 'codemode_background',\n kind: 'channel',\n direction: 'server-to-client',\n description: \"The session's running background code-mode scripts, in the hub frame payload property.\",\n input: BackgroundScriptsPayloadSchema,\n })),\n dynamic: [],\n});\nexport default apiContracts;\n"],"mappings":";;;;;;;AAGA,MAAa,iCAAiCA,QAAAA,KAAK,OAAO,EACxD,SAASA,QAAAA,KAAK,MACZA,QAAAA,KAAK,OAAO;CACV,IAAIA,QAAAA,KAAK,OAAO;CAChB,OAAOA,QAAAA,KAAK,OAAO;CACnB,WAAWA,QAAAA,KAAK,OAAO;CACvB,QAAQA,QAAAA,KAAK,MAAM,CAACA,QAAAA,KAAK,QAAQ,SAAS,GAAGA,QAAAA,KAAK,QAAQ,WAAW,CAAC,CAAC;AACzE,CAAC,CACH,EACF,CAAC;;AAGD,MAAa,gBAAA,GAAeC,gCAAAA,kBAAAA,CAAkB;CAC5C,SAAS;CACT,MAAM,CAAC;CACP,SAAU,CAAC,QAAQ,WAAW,CAAC,CAAW,KAAK,WAAW;EACxD,IAAI;EACJ;EACA,SAAS;EACT,QAAQ;EACR,MAAM;EACN,WAAW;EACX,aAAa;EACb,OAAO;CACT,EAAE;CACF,SAAS,CAAC;AACZ,CAAC"}
@@ -1,12 +1,13 @@
1
+ import { Type } from "typebox";
1
2
  //#region src/schemas/apiContracts.d.ts
2
- /** This server plugin contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
3
+ /** Agent tools and commands carry no HTTP surface; the page reads running background scripts from one hub channel. */
3
4
  export declare const apiContracts: {
4
5
  version: 1;
5
6
  protocols?: Record<string, string> | undefined;
6
7
  schemas?: Record<string, boolean | object> | undefined;
7
8
  http: {
8
9
  id: string;
9
- scope: "global" | "session" | "workspace";
10
+ scope: "host" | "session" | "workspace";
10
11
  basePath?: string | undefined;
11
12
  path: string;
12
13
  method: "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
@@ -34,7 +35,7 @@ export declare const apiContracts: {
34
35
  }[];
35
36
  sockets: {
36
37
  id: string;
37
- scope: "global" | "session" | "workspace";
38
+ scope: "host" | "session" | "workspace";
38
39
  description: string;
39
40
  availability?: string | undefined;
40
41
  service: string;
@@ -1 +1 @@
1
- {"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts"],"mappings":";;qBAGa"}
1
+ {"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts"],"mappings":";;;qBAea"}
@@ -1,10 +1,26 @@
1
1
  import { defineApiContract } from "@agimon-ai/po-core/apiContracts";
2
+ import { Type } from "typebox";
2
3
  //#region src/schemas/apiContracts.ts
3
- /** This server plugin contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
4
+ const BackgroundScriptsPayloadSchema = Type.Object({ scripts: Type.Array(Type.Object({
5
+ id: Type.String(),
6
+ label: Type.String(),
7
+ startedAt: Type.String(),
8
+ status: Type.Union([Type.Literal("running"), Type.Literal("reporting")])
9
+ })) });
10
+ /** Agent tools and commands carry no HTTP surface; the page reads running background scripts from one hub channel. */
4
11
  const apiContracts = defineApiContract({
5
12
  version: 1,
6
13
  http: [],
7
- sockets: [],
14
+ sockets: ["host", "workspace"].map((scope) => ({
15
+ id: "codemode.background.channel",
16
+ scope,
17
+ service: "po.hub",
18
+ member: "codemode_background",
19
+ kind: "channel",
20
+ direction: "server-to-client",
21
+ description: "The session's running background code-mode scripts, in the hub frame payload property.",
22
+ input: BackgroundScriptsPayloadSchema
23
+ })),
8
24
  dynamic: []
9
25
  });
10
26
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"apiContracts.mjs","names":[],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/po-core/apiContracts';\n\n/** This server plugin contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;AAGA,MAAa,eAAe,kBAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}
1
+ {"version":3,"file":"apiContracts.mjs","names":[],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/po-core/apiContracts';\nimport { Type } from 'typebox';\n\nexport const BackgroundScriptsPayloadSchema = Type.Object({\n scripts: Type.Array(\n Type.Object({\n id: Type.String(),\n label: Type.String(),\n startedAt: Type.String(),\n status: Type.Union([Type.Literal('running'), Type.Literal('reporting')]),\n }),\n ),\n});\n\n/** Agent tools and commands carry no HTTP surface; the page reads running background scripts from one hub channel. */\nexport const apiContracts = defineApiContract({\n version: 1,\n http: [],\n sockets: (['host', 'workspace'] as const).map((scope) => ({\n id: 'codemode.background.channel',\n scope,\n service: 'po.hub',\n member: 'codemode_background',\n kind: 'channel',\n direction: 'server-to-client',\n description: \"The session's running background code-mode scripts, in the hub frame payload property.\",\n input: BackgroundScriptsPayloadSchema,\n })),\n dynamic: [],\n});\nexport default apiContracts;\n"],"mappings":";;;AAGA,MAAa,iCAAiC,KAAK,OAAO,EACxD,SAAS,KAAK,MACZ,KAAK,OAAO;CACV,IAAI,KAAK,OAAO;CAChB,OAAO,KAAK,OAAO;CACnB,WAAW,KAAK,OAAO;CACvB,QAAQ,KAAK,MAAM,CAAC,KAAK,QAAQ,SAAS,GAAG,KAAK,QAAQ,WAAW,CAAC,CAAC;AACzE,CAAC,CACH,EACF,CAAC;;AAGD,MAAa,eAAe,kBAAkB;CAC5C,SAAS;CACT,MAAM,CAAC;CACP,SAAU,CAAC,QAAQ,WAAW,CAAC,CAAW,KAAK,WAAW;EACxD,IAAI;EACJ;EACA,SAAS;EACT,QAAQ;EACR,MAAM;EACN,WAAW;EACX,aAAa;EACb,OAAO;CACT,EAAE;CACF,SAAS,CAAC;AACZ,CAAC"}