pi-better-goal 0.1.2 → 0.1.4

package/LICENSE

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

package/README.md

@@ -1,105 +1,54 @@
 # pi-better-goal
 
-`pi-better-goal` is a Pi package that provides a `/goal` runtime with background-aware continuation for async subagents.
-
-It ships one extension that:
-
-- reads `pi-better-subagents` durable run metadata from the temp registry
-- treats current-parent `running` and `orphaned` subagents as active background work
-- owns `/goal` plus the `get_goal` and `update_goal` tools; only `/goal <objective>` can create a goal
-- shows the current goal with active and elapsed clocks in a right-aligned widget above custom footers such as `pi-observability`
-- publishes a typed activity snapshot on `pi.events`
-- adds goal-aware prompt context while background work is active, so foreground idleness is not confused with goal completion
-- sends a hidden follow-up when active background work drains to zero, including `callback:false` subagent runs
-- provides a `/better-activity` command and `get_background_activity` tool for inspection
-
-Goal state is stored as `pi-better-goal` custom entries in the Pi session. Existing `pi-codex-goal` entries are read for compatibility, but new state is written by this package.
-
-## Commands And Tools
-
-```text
-/goal
-/goal <objective>
-/goal pause
-/goal resume
-/goal clear
-/goal complete
-/better-activity
-```
-
-Model-callable tools:
-
-- `get_goal`
-- `update_goal`
-- `get_background_activity`
+`pi-better-goal` is a Pi extension for goal tracking with background-aware continuation.
 
-## Goal Clock
+## Quick Answer
 
-Only `/goal <objective>` can create or replace a goal; there is no model-callable
-goal creation tool. The right-aligned widget below the editor shows the objective,
-status, active time, and total elapsed time. Active time stops while paused. Both
-clocks freeze when the goal is completed and remain visible until the goal is
-cleared or replaced.
+Use `pi-better-goal` when a Pi session should keep an explicit objective visible until the foreground work and registered background activity are both done. It tracks active versus elapsed time and wakes the foreground when background work drains.
 
-The widget does not replace Pi's footer, so custom footer extensions such as
-`pi-observability` retain ownership of their layout and lifecycle.
+## Core Features
 
-Set `PI_BETTER_GOAL_DISABLE_WAKE=1` to disable hidden background-drain wakeups.
+- `/goal` runtime for starting, pausing, resuming, completing, and clearing the current objective.
+- A compact goal widget that does not replace Pi's footer.
+- Background activity tracking for subagents and other registered providers.
+- A follow-up wake when active background work drains to zero.
 
-## Install Locally
-
-From this directory:
+## Install
 
 ```sh
-npm install
-pi install .
+pi install npm:pi-better-goal
 ```
 
-For a one-off run:
+Try it for one run:
 
 ```sh
-pi -e .
+pi -e npm:pi-better-goal
 ```
 
-## Event Contract
-
-The extension emits these events on `pi.events`:
-
-- `pi-better-goal:ready` with `{ version }`
-- `pi-better-goal:activity` with an `ActivitySnapshot`
-- `pi-better-goal:terminal-attention` when terminal or unhealthy background work needs attention
-
-Other extensions can register providers by emitting `pi-better-goal:register-provider` with:
-
-```ts
-{
-  id: "provider-id",
-  label: "Provider label",
-  getActivity(ctx) {
-    return {
-      providerId: "provider-id",
-      label: "Provider label",
-      items: [
-        { id: "work-1", status: "running", active: true }
-      ]
-    };
-  }
-}
-```
+## When To Use
 
-The built-in provider id is `subagents`.
+Use this package for longer Pi sessions where subagents, background tasks, or other providers may still be active after the foreground message is idle.
 
-## Status Semantics
+Do not use it when you only need a note or checklist outside Pi's runtime state.
 
-For `pi-better-subagents`, active background work is:
+## Compatibility
 
-- `running`
-- `orphaned`
+| Requirement | Support |
+|-------------|---------|
+| Pi | Required |
+| Install method | `pi install npm:pi-better-goal` |
+| Background providers | Works with registered providers |
+| Development runtime | Node.js 22+ |
 
-`orphaned` is active but unhealthy. `completed`, `failed`, `killed`, `lost`, and `exited` are non-active terminal states. Batches are represented as normal per-run items; batch metadata is display-only.
-
-## Validation
+## Update Or Remove
 
 ```sh
-npm run verify
-```
+pi update npm:pi-better-goal
+pi remove npm:pi-better-goal
+```
+
+## More Detail
+
+- Repository: https://github.com/1aboveio/pi-better-harness
+- Detailed notes: https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-goal/docs/usage.md
+- License: https://github.com/1aboveio/pi-better-harness/blob/main/LICENSE

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "pi-better-goal",
-  "version": "0.1.2",
-  "description": "Background activity bridge for Pi goal continuations and async subagents.",
+  "version": "0.1.4",
+  "description": "Pi extension for goal tracking with background-aware continuation.",
+  "license": "MIT",
   "type": "module",
   "main": "src/index.ts",
   "files": [
@@ -65,4 +66,4 @@
   "engines": {
     "node": ">=22.0.0"
   }
-}
+}