forge-openclaw-plugin 0.2.27 → 0.2.28

package/dist/server/server/src/types.js

@@ -578,6 +578,7 @@ export const lifeForcePayloadSchema = z.object({
     spentTodayAp: z.number(),
     remainingAp: z.number(),
     forecastAp: z.number(),
+    plannedRemainingAp: z.number(),
     targetBandMinAp: z.number().min(0),
     targetBandMaxAp: z.number().min(0),
     instantCapacityApPerHour: z.number().min(0),
@@ -591,6 +592,7 @@ export const lifeForcePayloadSchema = z.object({
     stats: z.array(lifeForceStatStateSchema),
     currentCurve: z.array(lifeForceCurvePointSchema),
     activeDrains: z.array(lifeForceDrainEntrySchema),
+    plannedDrains: z.array(lifeForceDrainEntrySchema),
     warnings: z.array(lifeForceWarningSchema),
     recommendations: z.array(trimmedString),
     topTaskIdsNeedingSplit: z.array(z.string()),
@@ -887,6 +889,7 @@ export const calendarEventSchema = z.object({
     categories: z.array(z.string()).default([]),
     sourceMappings: z.array(calendarEventSourceSchema).default([]),
     links: z.array(calendarEventLinkSchema).default([]),
+    actionProfile: actionProfileSchema.nullable().default(null),
     remoteUpdatedAt: z.string().nullable(),
     deletedAt: z.string().nullable(),
     createdAt: z.string(),
@@ -906,6 +909,7 @@ export const workBlockTemplateSchema = z
     startsOn: dateOnlySchema.nullable().default(null),
     endsOn: dateOnlySchema.nullable().default(null),
     blockingState: z.enum(["allowed", "blocked"]),
+    actionProfile: actionProfileSchema.nullable().default(null),
     createdAt: z.string(),
     updatedAt: z.string(),
     ...ownershipShape
@@ -937,6 +941,7 @@ export const workBlockInstanceSchema = z.object({
     color: z.string(),
     blockingState: z.enum(["allowed", "blocked"]),
     calendarEventId: z.string().nullable(),
+    actionProfile: actionProfileSchema.nullable().default(null),
     createdAt: z.string(),
     updatedAt: z.string()
 });
@@ -954,6 +959,7 @@ export const taskTimeboxSchema = z.object({
     startsAt: z.string(),
     endsAt: z.string(),
     overrideReason: trimmedString.nullable(),
+    actionProfile: actionProfileSchema.nullable().default(null),
     createdAt: z.string(),
     updatedAt: z.string(),
     ...ownershipShape
@@ -2416,7 +2422,11 @@ const workBlockTemplateMutationShape = {
     userId: nonEmptyTrimmedString.nullable().optional()
 };
 export const createWorkBlockTemplateSchema = z
-    .object(workBlockTemplateMutationShape)
+    .object({
+    ...workBlockTemplateMutationShape,
+    activityPresetKey: trimmedString.nullable().optional(),
+    customSustainRateApPerHour: z.number().min(0).nullable().optional()
+})
     .superRefine((value, context) => {
     if (value.endMinute <= value.startMinute) {
         context.addIssue({
@@ -2448,6 +2458,8 @@ export const updateWorkBlockTemplateSchema = z
     startsOn: dateOnlySchema.nullable().optional(),
     endsOn: dateOnlySchema.nullable().optional(),
     blockingState: z.enum(["allowed", "blocked"]).optional(),
+    activityPresetKey: trimmedString.nullable().optional(),
+    customSustainRateApPerHour: z.number().min(0).nullable().optional(),
     userId: nonEmptyTrimmedString.nullable().optional()
 })
     .superRefine((value, context) => {
@@ -2482,6 +2494,8 @@ export const createTaskTimeboxSchema = z
     source: calendarTimeboxSourceSchema.default("manual"),
     status: calendarTimeboxStatusSchema.default("planned"),
     overrideReason: trimmedString.nullable().default(null),
+    activityPresetKey: trimmedString.nullable().optional(),
+    customSustainRateApPerHour: z.number().min(0).nullable().optional(),
     userId: nonEmptyTrimmedString.nullable().optional()
 })
     .superRefine((value, context) => {
@@ -2499,6 +2513,8 @@ export const updateTaskTimeboxSchema = z.object({
     endsAt: z.string().datetime().optional(),
     status: calendarTimeboxStatusSchema.optional(),
     overrideReason: trimmedString.nullable().optional(),
+    activityPresetKey: trimmedString.nullable().optional(),
+    customSustainRateApPerHour: z.number().min(0).nullable().optional(),
     userId: nonEmptyTrimmedString.nullable().optional()
 });
 export const recommendTaskTimeboxesSchema = z.object({
@@ -2530,6 +2546,8 @@ export const updateCalendarEventSchema = z
     availability: calendarAvailabilitySchema.optional(),
     eventType: trimmedString.optional(),
     categories: z.array(trimmedString).optional(),
+    activityPresetKey: trimmedString.nullable().optional(),
+    customSustainRateApPerHour: z.number().min(0).nullable().optional(),
     preferredCalendarId: nonEmptyTrimmedString.nullable().optional(),
     userId: nonEmptyTrimmedString.nullable().optional(),
     links: z
@@ -2582,6 +2600,8 @@ export const createCalendarEventSchema = z
     availability: calendarAvailabilitySchema.default("busy"),
     eventType: trimmedString.default(""),
     categories: z.array(trimmedString).default([]),
+    activityPresetKey: trimmedString.nullable().optional(),
+    customSustainRateApPerHour: z.number().min(0).nullable().optional(),
     preferredCalendarId: nonEmptyTrimmedString.nullable().optional(),
     userId: nonEmptyTrimmedString.nullable().optional(),
     links: z

package/dist/server/src/lib/snapshot-normalizer.js

@@ -394,6 +394,7 @@ export function normalizeForgeSnapshot(raw) {
             spentTodayAp: 0,
             remainingAp: 200,
             forecastAp: 0,
+            plannedRemainingAp: 0,
             targetBandMinAp: 170,
             targetBandMaxAp: 200,
             instantCapacityApPerHour: 0,
@@ -407,6 +408,7 @@ export function normalizeForgeSnapshot(raw) {
             stats: [],
             currentCurve: [],
             activeDrains: [],
+            plannedDrains: [],
             warnings: [],
             recommendations: [],
             topTaskIdsNeedingSplit: [],

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "forge-openclaw-plugin",
   "name": "Forge",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
-  "version": "0.2.27",
+  "version": "0.2.28",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.2.27",
+  "version": "0.2.28",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
   "type": "module",
   "license": "MIT",

package/skills/forge-openclaw/SKILL.md

@@ -56,6 +56,7 @@ Entity conversation rule:
 - Before you ask, decide the exact missing thing you need and how that answer will help you name, place, or save the record.
 - Prefer a progression of:
   concrete example or intent -> working name -> purpose or meaning -> placement in Forge -> operational details -> linked context.
+- Use those same playbooks for action-heavy non-Psyche flows such as `work_adjustment`, `preference_judgment`, `preference_signal`, and specialized `movement`, `life_force`, or `workbench` requests so the conversation starts from what the user is trying to understand, change, add, update, link, or run before you choose the route.
 - For emotionally meaningful non-Psyche records such as goals, habits, and notes, reflect the meaning before you ask for structure.
 - When the user is vague, ask for one small concrete example, stake, or desired outcome before you ask them to name the record.
 - When the user is clear, say what the record seems to be becoming and ask only for the last missing detail.
@@ -291,9 +292,25 @@ Use the wiki tools for file-first memory work:
 Use the health tools for review and reflective enrichment, not as the default CRUD architecture:
 `forge_get_sleep_overview`, `forge_get_sports_overview`, `forge_update_sleep_session`, `forge_update_workout_session`
 
+Use the dedicated domain routes for specialized surfaces that are not simple batch entities:
+
+- Movement lives under `/api/v1/movement/*`. Treat it as a dedicated timeline of `stays` and `trips`, not as generic batch CRUD. A `stay` means the user remained in the same place for a span of time. A `trip` means the user traveled between places. Use the movement routes when the user wants to understand time in place, travel behavior, specific stays or trips, known places, or selected-span aggregates such as "how long was I at home in the past 2 weeks?" or "when did I travel last month?".
+- Movement user actions are: query movement behavior, add a place or manual stay/trip overlay, update an existing stay/trip/place, or link a specific movement item to another Forge entity. Keep the explanation user-facing: where they stayed, when they traveled, what changed, and what this movement should be linked to.
+- When the user is filling a missing-data gap, the default write path is a user-defined overlay box, not a raw stay or trip patch. Use `POST /api/v1/movement/user-boxes/preflight` if you need to confirm overlap or snap to the nearest missing interval, then `POST /api/v1/movement/user-boxes` with `kind: "stay"` or `kind: "trip"`.
+- Use `PATCH /api/v1/movement/stays/:id` or `PATCH /api/v1/movement/trips/:id` only when the user is editing an existing recorded stay or recorded trip. Do not use those routes to fill a missing span.
+- If the user says something as explicit as "that missing block was me staying home", do not reopen broad intake. Confirm the interval or place only if it is still ambiguous, then create the overlay and read the timeline back.
+- Life Force lives under `/api/v1/life-force*`. Use `GET /api/v1/life-force` for the current energy overview, `PATCH /api/v1/life-force/profile` for durable profile changes, `PUT /api/v1/life-force/templates/:weekday` for weekday curve edits, and `POST /api/v1/life-force/fatigue-signals` for real-time tired or recovered signals.
+- Workbench lives under `/api/v1/workbench/*`. Use those dedicated routes for flow catalog reads, flow CRUD, runs, published outputs, node results, and latest-node-output reads instead of trying to force Workbench through the batch entity routes.
+- If you are unsure which specialized route family applies, check `forge_get_agent_onboarding` and use its `entityRouteModel.specializedDomainSurfaces` section before guessing.
+
 Use live work tools for `task_run`:
 `forge_log_work`, `forge_start_task_run`, `forge_heartbeat_task_run`, `forge_focus_task_run`, `forge_complete_task_run`, `forge_release_task_run`
 
+Use `forge_adjust_work_minutes` for `work_adjustment` when the user wants a truthful signed minute correction on an existing task or project rather than a fake live run or a retroactive new task.
+
+Use the dedicated Preferences action tools for `preference_judgment` and `preference_signal`:
+`forge_submit_preferences_judgment`, `forge_submit_preferences_signal`, `forge_update_preferences_score`
+
 Use `forge_post_insight` for `insight`.
 Use the calendar tools for provider sync and planning:
 `forge_get_calendar_overview`, `forge_connect_calendar_provider`, `forge_sync_calendar_connection`, `forge_create_work_block_template`, `forge_recommend_task_timeboxes`, `forge_create_task_timebox`

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -11,6 +11,9 @@ Forge correctly, and gather only the structure that still matters.
   with the entity label.
 - Start by saying what seems to matter here or what the record is becoming, then ask
   the next useful question.
+- Whenever you can, make the direction of the intake visible before the question by
+  naming what you think the user is trying to preserve, clarify, decide, schedule, or
+  make easier.
 - Ask only for what is missing or still unclear.
 - Before every question, decide the one missing thing you are trying to clarify.
 - Ask first for the missing thing that would change the record shape, title, or next
@@ -28,6 +31,8 @@ Forge correctly, and gather only the structure that still matters.
   short reflection -> one orienting question.
 - When the user is vague, ask for the smallest real example, desired outcome, or stake
   before you ask for wording.
+- For strategic, reflective, or emotionally meaningful non-Psyche records, ask what
+  feels important to keep true before you ask for labels, dates, or taxonomy.
 - When the user is clear, say what the record seems to be becoming and move straight to
   the last missing structural detail.
 - For straightforward logistical entities such as tasks, calendar events, work blocks,
@@ -36,6 +41,11 @@ Forge correctly, and gather only the structure that still matters.
 - For logistical records such as tasks, calendar events, work blocks, timeboxes, and
   task runs, use a fast path:
   one brief confirming sentence -> one operational question.
+- For action-heavy flows such as work adjustments, preference judgments, preference
+  signals, and specialized surface work in Movement, Life Force, or Workbench, first
+  ask what the user is trying to understand, change, add, update, link, or run, then
+  route to the dedicated action or surface path instead of pretending it is normal
+  CRUD.
 - Do not read schema fields out loud unless the user explicitly wants a checklist.
 - One focused question is the default. Ask two only when both questions serve the same
   job and the user is steady enough for it.
@@ -191,6 +201,35 @@ reusable records.
 - Once the distinction is clear, offer a candidate label yourself and invite
   correction instead of making the user wordsmith alone.
 
+## Opening move recipes
+
+Use these when you want the first turn to feel more guided and less form-like.
+
+Strategic record:
+
+- "This sounds like something you want to hold onto directionally, not just list.
+  What would feel important to keep true here?"
+
+Bounded-work record:
+
+- "This sounds like it wants to become a real piece of work. What outcome would make
+  it feel meaningfully real for now?"
+
+Reflective record:
+
+- "There is something here you do not want to lose. What feels most worth capturing
+  before we decide where to store it?"
+
+Reusable record:
+
+- "Before we settle the label, what future decision, comparison, or retrieval moment
+  should this help with?"
+
+Operational record:
+
+- "I can turn that into a concrete Forge action. What is the one timing, owner, or
+  placement detail that still needs to be decided?"
+
 ## Name, Define, Connect
 
 Once the core record is visible, use this short checkpoint.
@@ -208,6 +247,17 @@ Connect:
 - ask about links only after the record itself feels named and defined enough to stay
   stable
 
+## Close cleanly
+
+- Once the record has a working shape, tell the user what is now clear and what one
+  detail, if any, is still worth deciding.
+- If no detail is still decision-relevant, summarize the record in plain language and
+  move to the save.
+- Prefer "what I have now is..." or "what seems clear now is..." over a cold final
+  field check.
+- If the user gives a correction, revise the working formulation once and close again
+  instead of reopening the whole intake.
+
 ## Question design rules
 
 - Let each question have one job:
@@ -249,6 +299,8 @@ Connect:
   inside them.
 - After the user answers, prefer "what is becoming clearer is..." over a cold jump to
   the next field.
+- For reusable or abstract records, it is often better to say "what this would help
+  you decide later is..." before asking for the final wording.
 
 ## Ready-to-save check
 
@@ -644,6 +696,33 @@ Preferred opening question:
 
 - "Which task should I start?"
 
+## Work Adjustment
+
+Aim: correct tracked minutes truthfully without pretending a live run happened.
+
+Arc:
+
+1. Ask what existing task or project the minutes belong to.
+2. Ask whether time should be added or removed.
+3. Ask what real work or correction the adjustment is meant to capture.
+4. Ask for a short audit note only if the reason would otherwise be unclear later.
+
+Helpful follow-up lanes:
+
+- what record the correction belongs to
+- whether the adjustment is positive or negative
+- what truthful reason should stay attached to the correction
+
+Ready to act when:
+
+- the target task or project is clear
+- the minute delta is clear
+- the note is clear enough when an audit trail matters
+
+Preferred opening question:
+
+- "Which task or project should this time correction belong to?"
+
 ## Self Observation
 
 Aim: capture one observation clearly enough that it can support later reflection
@@ -741,6 +820,165 @@ Preferred opening question:
 
 - "Which calendar provider are you trying to connect, and what do you want Forge to do with it?"
 
+## Preference Judgment
+
+Aim: capture one pairwise preference decision with the right context, not just log a
+left-versus-right click.
+
+Arc:
+
+1. Ask what comparison the user is actually trying to settle.
+2. Ask which context or domain this judgment belongs to.
+3. Ask whether the result is left, right, tie, or skip.
+4. Ask for reason tags or strength only if they will improve later interpretation.
+
+Helpful follow-up lanes:
+
+- what the comparison is really about
+- which preference context should own the signal
+- whether the choice feels decisive, weak, tied, or not ready
+
+Ready to act when:
+
+- the left and right items are clear
+- the outcome is clear
+- the relevant context or profile is clear enough
+
+Preferred opening question:
+
+- "What comparison are you actually trying to settle here?"
+
+## Preference Signal
+
+Aim: store a direct preference signal such as favorite, veto, bookmark, or
+compare-later with the context that makes it interpretable later.
+
+Arc:
+
+1. Ask what item the user wants to mark.
+2. Ask what signal they want to give it.
+3. Ask what domain or context this belongs to if that is still unclear.
+4. Ask about strength only if the user is expressing a gradient rather than a simple mark.
+
+Helpful follow-up lanes:
+
+- what item is being marked
+- whether this is a favorite, veto, bookmark, neutral, or compare-later signal
+- what context makes the signal meaningful
+
+Ready to act when:
+
+- the item is clear
+- the signal type is clear
+- the context is clear enough if it changes interpretation
+
+Preferred opening question:
+
+- "What do you want Forge to remember about this item right now?"
+
+## Movement
+
+Aim: clarify whether the user wants to understand time in place, review travel
+behavior, add or update a stay or trip, inspect one place, or link movement context to
+another Forge record before choosing the dedicated route family.
+
+Arc:
+
+1. Ask whether the user is trying to query behavior, add something manually, update an existing movement item, or link movement to another Forge entity.
+2. Ask whether the focus is a stay, a trip, a place, a timeline window, or a selected span.
+3. Ask for the time window, place, or movement item that makes the question concrete.
+4. Ask what they are trying to notice, preserve, or answer through that movement context.
+5. Route to the dedicated movement read or write path once the surface is clear.
+
+Direct action rules:
+
+- If the user is clearly talking about a missing-data gap that should become a stay or
+  trip, use a user-defined movement box.
+- Preflight with `/api/v1/movement/user-boxes/preflight` when overlap or exact timing
+  is unclear, then create the overlay with `/api/v1/movement/user-boxes`.
+- Use `kind: "stay"` when the user stayed in one place and `kind: "trip"` when they
+  traveled.
+- Use raw `PATCH /api/v1/movement/stays/:id` or `/api/v1/movement/trips/:id` only for
+  editing an already-recorded stay or trip, not for filling a missing span.
+- When the user has already given the real answer, for example "I stayed home during
+  that missing block", do not ask a broad review question again. Confirm only the
+  interval or place if that is still ambiguous, then act.
+
+Helpful follow-up lanes:
+
+- whether the user wants time-in-place, travel history, one specific stay or trip, a
+  place summary, or a link
+- what time window, place, stay, trip, or selection is in scope
+- whether the question is behavioral, such as time at home, travel frequency, or place
+  distribution, versus an edit
+- whether the edit is a missing-gap overlay versus a true recorded stay/trip patch
+
+Ready to act when:
+
+- the movement surface is clear
+- the time range, place, stay, trip, or selection is clear enough
+- the user goal is clear enough to choose the route
+
+Preferred opening question:
+
+- "Are you trying to understand where you stayed and traveled, change one stay or trip, or answer a question about your movement behavior?"
+
+## Life Force
+
+Aim: clarify whether the user wants to review current energy state, change durable
+profile assumptions, edit weekday curves, or log a real-time fatigue signal.
+
+Arc:
+
+1. Ask whether the job is overview, profile change, weekday-template change, or fatigue signaling.
+2. Ask what part of the current energy picture feels most important or inaccurate.
+3. Ask what should stay true if they are changing profile or template assumptions.
+4. Route to the dedicated life-force path once the lane is clear.
+
+Helpful follow-up lanes:
+
+- whether the user wants explanation, editing, or signaling
+- what part of the energy model feels off or useful
+- what durable assumption versus real-time state is being changed
+
+Ready to act when:
+
+- the life-force lane is clear
+- the relevant weekday, profile field, or signal is clear enough
+- the user intent is clear enough to choose overview versus mutation
+
+Preferred opening question:
+
+- "Do you want to understand the current energy picture, change how Forge models it, or log how you feel right now?"
+
+## Workbench
+
+Aim: clarify whether the user wants to inspect a flow, edit it, run it, or inspect
+results so the agent uses the dedicated workbench contract instead of vague CRUD.
+
+Arc:
+
+1. Ask whether the job is flow discovery, one flow edit, execution, run history, published output, node-level inspection, or latest-node-output lookup.
+2. Ask which flow, slug, run, or node the request is about.
+3. Ask what the user is trying to learn, repair, or publish through that flow.
+4. Route to the dedicated workbench route family once the execution lane is clear.
+
+Helpful follow-up lanes:
+
+- whether the user wants structure, execution, or results
+- what exact flow or run is in scope
+- whether they need whole-flow output or node-level detail
+
+Ready to act when:
+
+- the workbench lane is clear
+- the flow, run, or node is clear enough
+- the requested read or mutation is clear enough to choose the route
+
+Preferred opening question:
+
+- "Are you trying to inspect a flow, change it, run it, or inspect one run's outputs?"
+
 ## Preference Catalog
 
 Aim: define a useful comparison pool, not just a list with no decision purpose.

package/skills/forge-openclaw/psyche_entity_playbooks.md

@@ -11,6 +11,15 @@ Forge without turning the conversation into a worksheet.
   experience, not like a schema form and not like a lecturer.
 - Name the emotional center or lived stake in plain language before the next question
   whenever that would help the user feel accurately understood.
+- Begin close to the living center of the moment:
+  danger,
+  shame,
+  grief,
+  anger,
+  collapse,
+  longing,
+  pressure,
+  or protection.
 - Stay collaborative. Do not claim certainty about what a belief, pattern, or mode
   "really is".
 - Start from lived experience before abstraction.
@@ -40,6 +49,8 @@ Forge without turning the conversation into a worksheet.
   the user can feel understood and correct you if needed.
 - When the material is charged, ask permission before moving from understanding into
   naming, challenging, or solution-finding.
+- Your first job is not interpretation. It is to make the moment feel graspable enough
+  that the user can stay with it and describe it.
 - Before you ask for change, naming, or repair, usually ask what the experience is
   trying to protect, prevent, or hold onto.
 - The warmth should come from accuracy and steadiness, not from extra softness,
@@ -58,6 +69,42 @@ Forge without turning the conversation into a worksheet.
 - When the user has said enough for an accurate working formulation, stop deepening and
   help them name it cleanly.
 
+## First reflection menu
+
+Use one brief reflection that matches the center of the moment before you deepen.
+
+Threat:
+
+- "Something in this landed as danger very quickly."
+
+Shame or collapse:
+
+- "The painful part seems to be what this starts to say about your worth."
+
+Pressure or control:
+
+- "It sounds like a part of you moved fast to keep things from getting worse."
+
+Loss or longing:
+
+- "There is a lot of ache in what mattered there."
+
+Confusion:
+
+- "The moment still feels tangled, so let us stay close to one slice of it."
+
+## Permission pivots
+
+Use these when you are about to move from understanding into naming, interpretation,
+or change.
+
+- "I think I have the shape of it more clearly now. Do you want me to stay with the
+  experience a little longer, or try putting language around it?"
+- "There may be a belief or mode here. Do you want a tentative formulation, or should
+  we keep clarifying the moment first?"
+- "I can help think about what might help next time, but I want to check whether the
+  experience itself feels understood enough first."
+
 ## Therapist micro-skills
 
 Use these in small doses rather than as a script.
@@ -281,6 +328,7 @@ When the lived experience is clear enough to name:
 - invite correction without defensiveness
 - if the wording is close but not right, revise it with the user once instead of
   restarting the whole intake
+- say in plain language what makes you think the proposed wording fits
 
 Example shape:
 
@@ -308,6 +356,15 @@ If the entity is not yet clear:
 - once the user accepts the wording, do not reopen deeper exploration unless they ask
   for it
 
+## Change and save pivots
+
+- Before change-oriented questions, check whether the user wants understanding,
+  naming, or next-step help.
+- When the user says the formulation lands, summarize it once in their language and
+  move to the write.
+- If another belief, value, pattern, mode, or note becomes visible, name it gently but
+  do not switch containers unless the user wants to.
+
 ## Psyche update loop
 
 Use this when the user is revising an existing Psyche record rather than creating one