@agimon-ai/po-goal 0.0.0-alpha.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,104 @@
+# @agimon-ai/po-goal
+
+Keep one objective and an optional token budget active across agent turns, with independent idle-time completion checking.
+
+Part of the [Po distribution](https://www.npmjs.com/package/@agimon-ai/po).
+
+Completed, cleared, or blocked goals no longer contribute active work instructions. Goal history
+is scoped to the repository. Lifecycle tools are private to the checker, never added to the working agent.
+
+> **Alpha:** Goal behavior may change between releases.
+
+## Requirements
+
+- Node.js 24 or newer
+- The Po background-work coordination service for automatic completion checks. If coordination is missing or unavailable, Goal does not assume the session is idle.
+
+## Install
+
+The seeded `modes.yaml` selects Goal in `default.packages`; it is not fixed host infrastructure.
+Keep it there or select it through a layer. Goal starts inactive.
+
+## Command grammar
+
+```text
+/goal <objective>
+/goal --tokens 100k <objective>
+/goal status
+/goal pause
+/goal resume
+/goal edit [--tokens 1.5m] <objective>
+/goal clear
+```
+
+Budgets accept compact values such as `100k` and `1.5m`. Starting or resuming a goal wakes the
+agent in both the CLI and server. After a turn settles, Goal waits for same-session subagents,
+runners, workflows, and their result handoffs, and for all pending messages to be processed.
+
+One bounded LLM check then evaluates the objective against the transcript and verification evidence.
+The checker alone receives `goal_complete`, `goal_continue`, and `goal_blocked`. Completion archives
+the evidence and removes the active goal. Incomplete work produces a targeted next-action prompt,
+not a generic completion claim. Genuine repeated external blockers retain the unfinished goal.
+
+New work, user input, edits, pause, session changes, or cancellation invalidate an in-flight verdict.
+Provider failures and invalid verdicts pause the goal without automatic retry loops. Use `/goal resume`
+after resolving the problem. Token and no-progress limits prevent further substantive continuation;
+a final idle check may still establish that the already-finished work is complete.
+
+## In the cockpit
+
+Once a session sets a goal, a `goal` group appears in the activity dock carrying the objective and
+how far along it is. Its kebab menu edits the objective and the token budget, or removes the goal,
+through `/goal` verbs. Removing archives to goal history and stops the turn in flight, so it asks first.
+
+## Settings
+
+The CLI reads settings from `$PI_CODING_AGENT_DIR/pi-goal.json` (default
+`~/.po/agent/pi-goal.json`). The defaults allow unlimited automatic turns and pause after three
+repeated tool-free outputs. The server uses those default continuation limits. The legacy
+`toolVisibility` setting is still decoded for compatibility but no longer exposes lifecycle tools.
+
+## State and history
+
+Live Goal state and `goal-check` audit records are stored in session entries. Checker token usage
+is included in Goal budget accounting. History is repository-scoped under:
+
+```text
+$PI_CODING_AGENT_DIR/goal-history/
+```
+
+The default history path is `~/.po/agent/goal-history/`. History retains up to 100 entries and
+1 MiB. Corrupt history files are quarantined instead of being interpreted as valid goals. Clearing
+or completing removes the active objective and status. Archived history remains until retention
+or explicit deletion removes it. Failed archival retains the goal instead of discarding it.
+
+## Public API
+
+```ts
+import { DEFAULT_GOAL_SETTINGS, parseGoalCommand, parseTokenBudget } from '@agimon-ai/po-goal';
+```
+
+The root also exports state-machine, history codec, accounting, safety, prompt, and tool
+types for embedding.
+
+## Development
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
+
+Maintained by [Agimon](https://agimon.ai/about).
+
+## License
+
+MIT
+
+Plugin entries live in `src/extensions`, with host-neutral runtime logic in `src/services` and host registrations in routed `src/extensions` surfaces. `src/models` owns goal state, accounting, transitions, and serialization. Named `src/services` folders handle history, persistence, prompts, and validation. Public helpers and types are exposed through flat `src/exports`.
+
+The native session contributions declare minor-mode owners and use the shared background-work contract. Request-private
+checker tools are validated before their effects are applied, with session and goal revision guards.
+Provider calls do not hold the command queue, so pause and clear remain responsive during inference.
+The main agent's ordinary tool policy is unchanged.

package/dist/apiContracts.cjs

@@ -0,0 +1,17 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = (0, require("@agimon-ai/po-core/apiContracts").defineApiContract)({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+exports.apiContracts = apiContracts;
+exports.default = apiContracts;
+
+//# sourceMappingURL=apiContracts.cjs.map

package/dist/apiContracts.cjs.map

@@ -0,0 +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 facet 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"}

package/dist/apiContracts.d.mts

@@ -0,0 +1,53 @@
+//#region src/schemas/apiContracts.d.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+export declare const apiContracts: {
+  version: 1;
+  protocols?: Record<string, string> | undefined;
+  schemas?: Record<string, boolean | object> | undefined;
+  http: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    basePath?: string | undefined;
+    path: string;
+    method: "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+    description: string;
+    availability?: string | undefined;
+    authentication: "device" | "none" | "owner";
+    parameters?: {
+      name: string;
+      in: "header" | "path" | "query";
+      required: boolean;
+      schema: boolean | object;
+    }[] | undefined;
+    body?: {
+      contentType: string;
+      contentTypes?: string[] | undefined;
+      required: boolean;
+      schema: boolean | object;
+    } | undefined;
+    responses: Record<string, {
+      description: string;
+      contentType?: string | undefined;
+      schema?: boolean | object | undefined;
+      events?: Record<string, boolean | object> | undefined;
+    }>;
+  }[];
+  sockets: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    description: string;
+    availability?: string | undefined;
+    service: string;
+    member: string;
+    direction: "client-to-server" | "server-to-client";
+    kind: "channel" | "method" | "state";
+    input: boolean | object;
+    output?: boolean | object | undefined;
+    errors?: boolean | object | undefined;
+  }[];
+  dynamic: string[];
+  gaps?: string[] | undefined;
+};
+//#endregion
+export { apiContracts as default };
+//# sourceMappingURL=apiContracts.d.mts.map

package/dist/apiContracts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts"],"mappings":";;qBAGa"}

package/dist/apiContracts.mjs

@@ -0,0 +1,13 @@
+import { defineApiContract } from "@agimon-ai/po-core/apiContracts";
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = defineApiContract({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+export { apiContracts, apiContracts as default };
+
+//# sourceMappingURL=apiContracts.mjs.map

package/dist/apiContracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.mjs","names":[],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/po-core/apiContracts';\n\n/** This facet 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"}