@dna113p/machines 0.2.0 → 0.3.1

package/services/laya/server.py

@@ -0,0 +1,230 @@
+# /// script
+# requires-python = ">=3.12,<3.14"
+# dependencies = ["laya==0.3.4", "fastapi>=0.115,<1", "uvicorn>=0.30,<1"]
+# ///
+"""Opt-in, single-checkpoint Laya Choice bridge. Run with uv run --script server.py.
+
+No model is loaded on import. Startup loads a real checkpoint once and fails if
+loading fails. This is a development/self-hosting bridge, not a public gateway.
+"""
+
+import argparse
+from contextlib import asynccontextmanager
+import hmac
+import json
+import math
+import os
+import threading
+from typing import Any, Callable, Literal
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.concurrency import run_in_threadpool
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+MAX_REQUEST_BYTES = 65_536
+DEFAULT_CHECKPOINT = "convaiinnovations/laya"
+
+
+class ContextLimitError(ValueError):
+    """The SDK would silently truncate evidence, instructions, or options."""
+
+
+class ChoiceQuestion(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    type: Literal["choice"]
+    instructions: str = Field(min_length=1)
+    criteria: dict[str, str | None] = Field(min_length=2)
+
+    @field_validator("instructions")
+    @classmethod
+    def nonblank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("Empty instructions")
+        return value
+
+    @field_validator("criteria")
+    @classmethod
+    def valid_choices(cls, value: dict[str, str | None]) -> dict[str, str | None]:
+        if any(not key.strip() or key != key.strip()
+               or (description is not None and not description.strip())
+               for key, description in value.items()):
+            raise ValueError("Invalid choices")
+        return value
+
+
+class Questions(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    decision: ChoiceQuestion
+
+
+class ChoiceRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    model: str = Field(min_length=1)
+    state: str = Field(min_length=1)
+    questions: Questions
+
+    @field_validator("state", "model")
+    @classmethod
+    def nonblank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("Empty value")
+        return value
+
+
+def check_context(tokenizer: Any, state: str, instructions: str, options: list[str],
+                  max_len: int, head_max_len: int) -> None:
+    """Reject every truncation path in the pinned Laya 0.3.4 Choice formatter."""
+    def count(text: str) -> int:
+        return len(tokenizer(text.replace(tokenizer.mask_token, " "),
+                             add_special_tokens=False)["input_ids"])
+
+    head = count(f"choice question: {instructions}")
+    option_lengths = [count(" " + option) for option in options]
+    # The SDK first caps individual option descriptions at 48 tokens, then may
+    # shrink all options to reserve 16 tokens of its question/option head budget.
+    option_tokens = sum(length + 1 for length in option_lengths)  # MASK per option
+    budget = head_max_len - option_tokens
+    if (any(length > 48 for length in option_lengths) or budget < 16
+            or head > max(8, budget)
+            or head + option_tokens + count(state) + 4 > max_len):
+        raise ContextLimitError("Request exceeds the checkpoint's untruncated context budget")
+
+
+def load_predictor(checkpoint: str, subfolder: str | None, device: str | None) -> Any:
+    # Optional ML dependencies are deliberately imported only during startup.
+    import laya
+    from laya.common import render_options
+
+    agent = laya.load(checkpoint, subfolder=subfolder, device=device)
+
+    class Predictor:
+        def predict(self, state: str, questions: dict[str, Any]) -> Any:
+            for question in questions.values():
+                internal = {"t": "choice", "ins": question["instructions"], "crit": question["criteria"]}
+                check_context(agent.tok, state, question["instructions"], render_options(internal),
+                              agent.cfg.get("max_len", 512), agent.cfg.get("head_max_len", 192))
+            return agent.predict(state, questions)
+
+    return Predictor()
+
+
+def normalized_response(raw: Any, model: str, choices: dict[str, Any]) -> dict[str, Any]:
+    """Only validated classification fields leave the bridge, never SDK diagnostics."""
+    answer = raw["answers"]["decision"]
+    probabilities = answer["probabilities"]
+    confidence = answer["confidence"]
+    choice = answer["choice"]
+
+    def probability(value: Any) -> bool:
+        return type(value) in (int, float) and math.isfinite(value) and 0 <= value <= 1
+
+    if (answer["type"] != "choice" or not isinstance(choice, str) or choice not in choices
+            or not isinstance(probabilities, dict) or probabilities.keys() != choices.keys()
+            or not all(probability(value) for value in probabilities.values())
+            or abs(sum(probabilities.values()) - 1) > 0.001
+            or probabilities[choice] < max(probabilities.values())
+            or not probability(confidence)):
+        raise ValueError("Invalid Choice result")
+    # The server's configured identifier names its loaded checkpoint; the request
+    # cannot select arbitrary Hugging Face repositories or local filesystem paths.
+    return {"model": model, "answers": {"decision": {
+        "type": "choice", "choice": choice,
+        "probabilities": probabilities, "confidence": confidence,
+    }}}
+
+
+def create_app(*, model: str = "laya", checkpoint: str = DEFAULT_CHECKPOINT,
+               subfolder: str | None = None, device: str | None = None,
+               api_key: str | None = None, loader: Callable[[], Any] | None = None) -> FastAPI:
+    if not model.strip() or not checkpoint.strip():
+        raise ValueError("Model and checkpoint must be non-empty")
+    if api_key is not None and (not api_key or any(not 33 <= ord(char) <= 126 for char in api_key)):
+        raise ValueError("LAYA_API_KEY must be a non-empty ASCII Bearer token")
+    inference_lock = threading.Lock()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        app.state.predictor = await run_in_threadpool(
+            loader if loader is not None else lambda: load_predictor(checkpoint, subfolder, device)
+        )
+        try:
+            yield
+        finally:
+            del app.state.predictor
+
+    app = FastAPI(title="Machines Laya Choice bridge", lifespan=lifespan,
+                  docs_url=None, redoc_url=None, openapi_url=None)
+
+    def authorize(request: Request) -> None:
+        if api_key is not None and not hmac.compare_digest(
+            request.headers.get("authorization", "").encode(), f"Bearer {api_key}".encode()
+        ):
+            raise HTTPException(401, "Unauthorized")
+
+    @app.get("/health")
+    def health(request: Request) -> dict[str, Any]:
+        authorize(request)
+        if not hasattr(app.state, "predictor"):
+            raise HTTPException(503, "Checkpoint not loaded")
+        return {"status": "ready", "service": "machines-laya", "model": model}
+
+    def evaluate(payload: ChoiceRequest) -> dict[str, Any]:
+        # Reject concurrent work instead of creating an unbounded inference queue.
+        if not inference_lock.acquire(blocking=False):
+            raise HTTPException(503, "Laya is busy; no automatic retry")
+        try:
+            try:
+                raw = app.state.predictor.predict(payload.state, payload.questions.model_dump())
+            except ContextLimitError:
+                raise HTTPException(413, "Request exceeds the checkpoint's untruncated context budget") from None
+            except Exception:
+                raise HTTPException(500, "Laya inference failed") from None
+            try:
+                return normalized_response(raw, model, payload.questions.decision.criteria)
+            except Exception:
+                raise HTTPException(502, "Laya returned an invalid Choice response") from None
+        finally:
+            inference_lock.release()
+
+    @app.post("/v1/systemone")
+    async def system_one(request: Request) -> dict[str, Any]:
+        authorize(request)
+        body = bytearray()
+        async for chunk in request.stream():
+            body.extend(chunk)
+            if len(body) > MAX_REQUEST_BYTES:
+                raise HTTPException(413, "Request exceeds 64 KiB")
+        try:
+            payload = ChoiceRequest.model_validate(json.loads(body))
+        except (ValueError, ValidationError, UnicodeError):
+            # Default validation errors can echo the original evidence.
+            raise HTTPException(422, "Expected one Choice question named decision and string state") from None
+        if payload.model != model:
+            raise HTTPException(404, "Unknown served model")
+        return await run_in_threadpool(evaluate, payload)
+
+    return app
+
+
+def main() -> None:
+    import uvicorn
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8001)
+    parser.add_argument("--model", default="laya", help="Public identifier expected by LAYA_MODEL")
+    parser.add_argument("--checkpoint", default=DEFAULT_CHECKPOINT)
+    parser.add_argument("--subfolder", default=None)
+    parser.add_argument("--device", default=None, help="For example cpu, cuda, or mps")
+    args = parser.parse_args()
+    api_key = os.environ.get("LAYA_API_KEY")
+    if args.host not in ("127.0.0.1", "::1", "localhost") and not api_key:
+        parser.error("Non-loopback binding requires LAYA_API_KEY; use a TLS proxy on untrusted networks")
+    app = create_app(model=args.model, checkpoint=args.checkpoint, subfolder=args.subfolder,
+                     device=args.device, api_key=api_key)
+    # One process, one resident model. No auto-reload or request/evidence logging.
+    uvicorn.run(app, host=args.host, port=args.port, access_log=False)
+
+
+if __name__ == "__main__":
+    main()

package/skills/machine-builder/SKILL.md

@@ -1,24 +1,74 @@
 ---
 name: machine-builder
-description: Create or edit TypeScript workflow definitions for the Machines runtime, including discovery metadata, Agent roles, Operations, Human decisions, and transitions. Use for reusable Machines workflows, not unrelated XState applications or runtime internals.
+description: Use proactively for multi-step implementation, debugging, review, or verification that benefits from explicit stages and decisions. Discover and use a suitable Machine, or design and verify a task-specific TypeScript workflow. The user need not explicitly request Machines; keep trivial work direct.
 ---
 
 # Machine builder
 
+For project-wide workflow setup owned by the project orchestrator, start with
+[machine-project-setup](../machine-project-setup/SKILL.md). It chooses coverage
+for the project's major work; use this builder to implement individual definitions.
+Do not repeat project setup for each assignment.
+
+Before starting multi-step work, discover suitable Machines instead of waiting for
+the user to ask for one. Use an existing workflow when it fits; writing a new
+Machine is not the goal. For delegated work, follow
+[machine-delegation](../machine-delegation/SKILL.md). If already executing an Agent
+state inside a Machine, do that assigned work directly rather than recursively
+wrapping it in another Machine. Preserve the authorized effects and model budget.
+
+Decide which workflow serves the user's task. Creating or adapting a project
+Machine is an implementation choice within the authorized task; proceed without
+separate permission to author it. Choose its states, roles, branches, and completion
+conditions from the work itself. A Machine can be useful for one assignment;
+future reuse is optional. Keep small steps direct when a workflow adds no value.
+
 Use [Authoring Machines](../../docs/authoring.md) for the definition contract and
 examples. Before choosing a workflow, inspect available Machines and Agent presets
 with `machine list` and `machine agents`, or the connected `machine_list` and
-`machine_agents` tools. Adapt a matching workflow when it fits the user's scope.
+`machine_agents` tools. Reuse, adapt, or create a definition based on the task's
+needs. Existing Machines and examples are starting points, not a fixed menu.
+Make consequential checks and decisions explicit in states when they need to
+control progress. Choose the complexity needed to complete the task reliably.
+
+Look for common task sequences and recurring manual workflows while doing the
+work. Convert them into Machines when explicit steps would improve repeatability
+or code quality. Parameterize assignment details so the workflow can serve the
+next task. Build around the process observed in the project.
+
+Use deterministic Operations for mechanically checkable work: project type checks,
+focused tests, linting, schema or artifact validation, and filesystem or Git
+invariants. Inspect actual exit codes and outputs, record useful evidence, and
+route failures to repair, escalation, or a blocked result. Required checks must
+pass before success; an Agent's claim of completion is not verification. Use
+Agents for judgment and open-ended changes, with bounded repair loops where
+appropriate. Choose checks that establish the task's completion conditions.
 
 For a new definition, capture the intended states, returned events, and completion
 condition. Put the definition in the requested location; project `.machines/` is
-the default for project-specific work. Global installation is a separate choice.
+the default for project-specific work. Authoring a Machine does not expand the
+task's authorized effects; preserve that scope when running it. Global installation
+is a separate choice.
 
 Export a non-empty one-line `description` explaining when to use the Machine and
-a default factory accepting the supplied primitives and input string. Declare
-semantic `agentRoles` for named Agents, then use those exact roles in states.
+a default factory accepting the supplied primitives and input. Import runtime
+types from `@dna113p/machines`, for example:
+
+```ts
+import type { Event, MachinePrimitives } from "@dna113p/machines";
+```
+
+Use public package exports for runtime imports and relative imports for
+project-local helpers. A sibling checkout's `src/` is not the package interface.
+Install the package locally when editor or type-checker resolution is needed;
+the launcher supplies primitives and type-only imports are erased at execution.
+
+Declare semantic `agentRoles` for named Agents, then use those exact roles in states.
 Select harnesses and models through presets, keeping environment details out of
-workflow policy. The [bundled examples](../../dist/examples/) show runtime usage
+workflow policy. A provider usage limit normally swaps to a fallback preset or
+waits; give an Agent state `onLimit: "<event>"` only when the workflow itself
+should branch at a limit, for example to skip a cross-provider review or ask a
+Human. The [bundled examples](../../dist/examples/) show runtime usage
 after the package is built; authoring examples in the guide also work before a build.
 
 Keep module initialization side-effect free: discovery imports definitions and

package/skills/machine-delegation/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: machine-delegation
+description: Use proactively before delegating implementation, debugging, review, research, or other bounded multi-step work. Prefer Machine runs to native sub-agents, reusing or creating a scoped workflow with explicit outcomes. The user need not name Machines; keep trivial work direct.
+---
+
+# Machine delegation
+
+When acting as project orchestrator, consult the project's `.machines/README.md`
+or existing workflow map before choosing a route. On initial setup or meaningful
+missing/stale coverage, use [machine-project-setup](../machine-project-setup/SKILL.md)
+to build the useful project workflows before repeated delegation. Reuse established
+coverage for normal tasks; workers do not repeat project setup.
+
+Use a Machine run as the unit of delegated work. The coordinating agent owns the
+user's goal, task boundaries, and integration of results; the Machine owns its
+states, verification, retries, and escalation. Complete small local steps directly.
+Launch a suitable Machine instead of native sub-agents without requiring the user
+to name this skill. Discovery is a decision step, not the completed work: start the
+selected workflow and inspect its result. Use deterministic Operations for checks
+rather than paying another model to run commands. Never broaden permissions or
+model spending merely to satisfy the preference. If the tools or a safe workflow
+are unavailable, state the concrete reason for proceeding directly.
+
+If already running as a Machine's Agent state, execute that bounded assignment
+and return its evidence/outcome. Do not delegate it again unless explicitly asked
+for bounded nested work by the owning assignment.
+
+## Choose or create the Machine
+
+Inspect `machine_list` and `machine_agents` in the target workspace. MCP requires
+an absolute `cwd`; Pi uses the conversation's working directory. With only a shell,
+run `machine list` and `machine agents` there (`./machine` in a source checkout).
+See [Integrations](../../docs/integrations.md) if the tools are unavailable.
+
+Evaluate candidate Machines by their descriptions, then read their returned source
+paths or use `machine show <name>`. Check input format, Agent roles, actual workspace,
+output artifacts, final states, and effects such as commits or publishing. A matching
+name alone does not establish that the workflow fits the delegated task.
+
+Decide whether to reuse, adapt, or create a Machine using
+[machine-builder](../machine-builder/SKILL.md). A generic Machine's ability to
+accept the task as a prompt is only one consideration; choose a workflow whose
+states express the decisions and verification the task needs. Authoring a
+task-specific Machine is part of the delegated work and needs no separate
+permission. Keep global installation and unrelated workflow changes outside that
+scope. Use the [delegation starter](references/delegation-machine.md) when there is no existing
+result contract to follow. Add review or bounded revision states when the work
+needs them, and Human states for decisions that belong to the user.
+
+List again after edits. Resolve required roles using exact preset names from
+`machine_agents`, passing role-to-preset overrides at launch. A listing's readiness
+only checks metadata and bindings; the harness still needs to be installed and
+configured. The built-in `codex` preset is read-only. Choose or configure a preset
+that can perform the authorized task, following the builder's authoring guide.
+
+## Supply a complete assignment
+
+Workers do not inherit this conversation. Supply the context needed to act:
+
+- The bounded objective, relevant facts, and acceptance criteria.
+- The absolute workspace, files or references to read, and ownership of any edits.
+- Applicable constraints, permitted effects, and what should produce a blocked outcome.
+- A result location readable by the coordinator, and what evidence it must contain.
+
+Follow the selected Machine's input contract. MCP/Pi accept JSON-serializable
+input; CLI positional input is text, while `--input-file <file|->` accepts JSON.
+Keep task details in input rather than hardcoding each assignment into a new
+workflow. Give each run a distinct artifact destination.
+
+**Plan result retrieval before launch.** `machine_status` exposes state, Human
+requests, errors, and optional JSON Machine output, not arbitrary Agent transcripts
+or event payloads. Have the Machine return useful JSON output, have the worker
+write a report, or capture its returned event and save it in an Operation. The
+Machine-owned options also support read-only Agent presets. Include findings or
+changes, verification evidence, and blockers. An Operation's writes must stay
+within the task's scope even when the Agent itself is read-only.
+
+Delegate independent tasks concurrently only when their workspaces and writes are
+compatible. Use isolated worktrees for overlapping code changes; runs do not create
+worktrees automatically. Pass prerequisites through explicit artifacts before
+starting dependent work. Give workers bounded assignments to complete themselves;
+nested delegation needs an explicit reason and scope.
+
+## Launch and supervise
+
+Call `machine_start` with the discovered Machine name, task input, workspace, and
+any preset overrides. Record the returned `run.id` with its task, workspace,
+expected success state, and result path. Start once; a slow response is not a
+reason to launch a duplicate. If the launch response is lost, inspect this session's
+statuses before deciding whether another run is needed.
+
+Continue independent work while the run executes. Read `machine_status` with its
+exact `runId` when progress or a result is needed, spacing checks rather than
+polling continuously. Interpret the current snapshot:
+
+| Status | Coordinator action |
+| --- | --- |
+| `running` | Continue independent work or wait before checking again. |
+| `waiting` | Read `human.prompt` and its choices or suggestions. Relay the question if the user's answer is not already clear from the conversation. Submit that answer with `machine_respond`, using the exact `runId` and current `human.requestId`; restrictive choices require an exact string. |
+| `completed` | Check the final state and read the result artifacts. A final state such as `blocked` or `rejected` also counts as a completed run. |
+| `failed` | Read the error and inspect partial effects. Correct the cause or report the blocker before considering a fresh run. |
+
+Preserve existing user authorization when answering Human requests, and surface a
+new decision when the request requires one. A desire to finish is not an answer.
+
+To follow a run this session did not start, such as a ticket a daemon runs, use
+`machine watch <ticket-or-run-id>` where run status is published (`machine runs`
+lists what can be watched; `--all` adds runs that already ended). Watching only
+shows the run on this session's status line: it neither owns nor answers it.
+
+The CLI fallback is `machine run <name> [--agent role=preset] -- <input>` in the
+target workspace. It waits for completion and uses terminal Human input; retain
+the shell session if running it asynchronously. It does not return an MCP run ID.
+
+The current tools have no per-run cancel, arbitrary message, or resume operation.
+`machine_respond` answers a pending Human request; it cannot steer a running Agent.
+Edits to a definition apply to future runs. MCP/Pi runs belong to their session:
+closing or reloading it terminates owned work, and only a limited number of finished
+snapshots are retained. Keep needed evidence in artifacts. After interruption,
+inspect existing effects before restarting; a new run is not a continuation or rollback.
+
+## Collect and integrate
+
+Finish only after the intended final state and requested artifact or effect are
+verified. Read the report and inspect relevant changes or checks, then integrate
+the result into the user's task. If evidence is missing, treat that as incomplete
+work even if the run says `completed`. Report the useful result, any blocker, and
+artifact paths; a run ID alone is not the delegated deliverable.

package/skills/machine-delegation/references/delegation-machine.md

@@ -0,0 +1,90 @@
+# A Machine for one delegated assignment
+
+Use this starter when no existing Machine provides the needed task and result
+contract. Save it as `.machines/delegate-task.ts`, then adapt verification to the
+assignment using [Authoring Machines](../../../docs/authoring.md). It accepts a JSON
+input string containing `task` and an absolute `resultPath` that does not yet exist.
+The Agent works in the launch workspace and returns a summary; an Operation saves
+the result, so the Agent can use a read-only preset for research or review.
+
+```ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute } from "node:path";
+import type { Event, MachinePrimitives } from "@dna113p/machines";
+
+export const description = "Completes a bounded assignment and saves its outcome and evidence as JSON.";
+export const agentRoles = { worker: "Performs the delegated assignment" };
+
+export default function delegateTask(
+  { machine, agent, operation, final }: MachinePrimitives,
+  input: string,
+) {
+  const assignment = JSON.parse(input);
+  if (
+    typeof assignment?.task !== "string" || assignment.task.trim() === "" ||
+    typeof assignment?.resultPath !== "string" || !isAbsolute(assignment.resultPath)
+  ) {
+    throw new Error("Expected task and absolute resultPath in JSON input");
+  }
+
+  let result: { outcome: string; summary: string } | undefined;
+  const capture = ({ event }: { event: Event }) => {
+    if (typeof event.summary !== "string" || event.summary.trim() === "") {
+      throw new Error("Worker must return a non-empty summary with evidence or blockers");
+    }
+    result = { outcome: event.type, summary: event.summary };
+  };
+
+  return machine({
+    initial: "work",
+    states: {
+      work: agent(
+        `${assignment.task}\n\nComplete this bounded assignment yourself. ` +
+        "Return completed when its acceptance criteria are met, or blocked when " +
+        "you cannot proceed within scope. Include a summary string in the final " +
+        "Machines event with findings or changes, verification evidence, and blockers. " +
+        "The Machine saves that summary; you do not need to write a separate report.",
+        {
+          completed: { target: "save", actions: capture },
+          blocked: { target: "save", actions: capture },
+        },
+        { using: "worker", cwd: process.cwd() },
+      ),
+      save: operation(async () => {
+        if (result === undefined) throw new Error("Worker result is missing");
+        await mkdir(dirname(assignment.resultPath), { recursive: true });
+        await writeFile(assignment.resultPath, JSON.stringify(result, null, 2) + "\n", {
+          flag: "wx",
+        });
+        return { type: result.outcome };
+      }, { completed: "done", blocked: "blocked" }),
+      done: final(),
+      blocked: final(),
+    },
+  });
+}
+```
+
+Discover the definition and presets, then bind `worker` to a discovered preset.
+For example, if `codex` is available and configured, launch a read-only review via
+MCP with these arguments (replace the example paths and task):
+
+```json
+{
+  "cwd": "/absolute/project",
+  "machine": "delegate-task",
+  "input": "{\"task\":\"Read src/parser.ts and its tests. Identify unhandled input cases with file and line evidence. Leave source files unchanged.\",\"resultPath\":\"/absolute/project/.machines/results/parser-review-01.json\"}",
+  "agents": { "worker": "codex" }
+}
+```
+
+The saved JSON has `outcome` and `summary`. Read it after the run finishes; `done`
+means the worker reported completion and its summary was saved. `blocked` is a
+terminal outcome requiring the coordinator's attention. This starter validates
+the result contract, not the truth of the worker's claims: inspect its evidence,
+and add verification Operations for conditions the Machine can check directly.
+
+Before real work, exercise both outcomes with fake runners through the public
+runtime or launcher. Also check that a missing summary fails and that an existing
+result file is preserved. Use a fresh result path for each run; retrying after a
+write failure may repeat completed Agent work, so inspect partial effects first.