@inneranimalmedia/agentsam-sdk 2.4.0 → 2.5.0

package/skills/agentsam-jr-dev/references/real-application-logic.md

@@ -0,0 +1,156 @@
+# Real Application Logic — Build/Inspection Gate
+
+Use this checklist when AgentSam builds, inspects, or revises an application,
+website with behavior, service, microservice, CLI, or cross-layer feature.
+
+The purpose is to distinguish a real implementation from a convincing-looking
+surface.
+
+## 1. State the behavior
+
+Write one sentence describing what a user/system can now actually do.
+
+Bad:
+
+> Add an agent dashboard.
+
+Better:
+
+> A signed-in user can start an agent run, watch its live task state, cancel it,
+> and reopen its persisted result later.
+
+That sentence exposes the required mechanics.
+
+## 2. Find the current architecture
+
+Prove where these concerns live today:
+
+- entrypoint,
+- UI/client,
+- API/action boundary,
+- business/domain logic,
+- persistence,
+- identity/auth,
+- background work,
+- external providers,
+- tests,
+- deployment/runtime.
+
+Do not create a second architecture because the first one took effort to find.
+
+## 3. Identify authority
+
+For every important state value, ask:
+
+> Who is allowed to declare this true?
+
+Examples:
+
+- `isMenuOpen` -> frontend UI state,
+- `currentUserId` -> verified backend identity,
+- `paymentSucceeded` -> payment provider/backend webhook,
+- `agentRun.status` -> agent runtime/store,
+- `deployment.version` -> deployment system,
+- `file root hash` -> Merkle computation/evidence store.
+
+Many broken applications are authority bugs disguised as UI bugs.
+
+## 4. Trace the complete flow
+
+For mutations:
+
+```text
+intent
+ -> input
+ -> validation
+ -> authorization
+ -> business rule
+ -> mutation/provider operation
+ -> persistence/event
+ -> response
+ -> visible state
+```
+
+For reads:
+
+```text
+question/view
+ -> query/request
+ -> authorization/scope
+ -> authoritative source
+ -> bounded result
+ -> transformation
+ -> presentation
+```
+
+Mark every missing edge before coding.
+
+## 5. Handle non-happy paths
+
+At minimum consider:
+
+- invalid input,
+- unauthenticated/unauthorized request,
+- missing resource,
+- provider/network failure,
+- timeout/cancellation,
+- duplicate/retried request,
+- partial failure,
+- stale client state,
+- empty/loading state.
+
+Do not add elaborate machinery for impossible cases, but do not pretend the
+happy path is the whole application either.
+
+## 6. Verify reality
+
+Prefer the strongest available proof:
+
+1. real end-to-end path,
+2. integration test against real local dependency,
+3. contract/API test,
+4. unit test,
+5. static/type/lint check.
+
+A screenshot proves appearance. It does not prove persistence, authorization,
+API correctness, side effects, cancellation, or recovery.
+
+## 7. Inspect/revision questions
+
+When auditing an existing project, ask:
+
+- Is there more than one source of truth for the same state?
+- Does frontend code hold secrets or claim authority it should not have?
+- Does the backend trust client-supplied identity/ownership fields?
+- Are runtime entrypoints overloaded with business logic?
+- Are shared packages actually portable, or importing host-specific internals?
+- Are API contracts explicit and validated?
+- Are writes idempotent where retries can occur?
+- Are errors observable and actionable?
+- Are generated/demo/reference files being mistaken for runtime authority?
+- Does the deployment path match the development path closely enough to trust?
+- Can an agent retrieve the exact evidence it needs without flooding context?
+
+## 8. Junior explanation after implementation
+
+When reporting back, explain in this order:
+
+```text
+What changed
+  user-visible behavior
+
+How it works
+  3-7 step real flow
+
+Where it lives
+  exact important files/modules
+
+Why the boundaries are there
+  authority/security/state reasons
+
+How we proved it
+  tests/commands/real runtime evidence
+```
+
+Keep implementation detail proportional to the user's curiosity, but never hide
+an unimplemented layer behind simplified language.

package/skills/agentsam-jr-dev/references/web-application-fundamentals.md

@@ -0,0 +1,240 @@
+# Web/Application Fundamentals — Jr Dev Reference
+
+Use this reference when teaching web application architecture. Adapt it to the
+actual repository instead of assuming every project uses these exact directory
+names.
+
+## HTTP
+
+HTTP is a request/response protocol: one program sends a structured request to
+another program, and the receiving program sends a structured response back.
+
+A simplified exchange:
+
+```text
+browser/client                         server/backend
+      |                                      |
+      | GET /api/models                      |
+      |------------------------------------->|
+      |                                      | find/compute result
+      | 200 OK                               |
+      | { "models": [...] }                 |
+      |<-------------------------------------|
+```
+
+An HTTP request commonly contains:
+
+- method (`GET`, `POST`, `PATCH`, `DELETE`, ...),
+- URL/path,
+- headers,
+- optional body.
+
+A response commonly contains:
+
+- status (`200`, `201`, `400`, `401`, `403`, `404`, `500`, ...),
+- headers,
+- optional body.
+
+The method is a convention about intent, not magic business logic:
+
+- `GET` usually reads,
+- `POST` usually creates or starts an action,
+- `PUT` usually replaces,
+- `PATCH` usually changes part,
+- `DELETE` usually removes.
+
+The backend still decides what is valid and authorized.
+
+## API
+
+An API is an interface another program can use. An HTTP API defines routes and
+message shapes such as:
+
+```text
+POST /api/runs
+GET  /api/runs/:id
+POST /api/runs/:id/cancel
+```
+
+The route is the door. The business logic behind the door is the important part.
+
+## Frontend
+
+The frontend/client is the code responsible for what the user directly
+interacts with in their browser/app process.
+
+Typical responsibilities:
+
+- rendering UI,
+- handling clicks/typing/navigation,
+- temporary UI state,
+- requesting trusted operations from the backend,
+- presenting loading/success/error states.
+
+A frontend should not be trusted with server secrets merely because JavaScript
+can technically contain them. Browser code is delivered to the user's machine
+and can be inspected or modified by that user.
+
+## Backend
+
+The backend/server is the trusted application runtime for operations that need a
+controlled authority.
+
+Typical responsibilities:
+
+- request validation,
+- authorization,
+- secrets/provider credentials,
+- database writes,
+- trusted model/provider calls,
+- filesystem/Git/cloud operations,
+- durable business rules,
+- rate limits and policy.
+
+A backend may run in a traditional server, serverless function, Worker, container,
+VM, local process, or another runtime. "Backend" describes responsibility more
+than hosting technology.
+
+## Shared/contracts
+
+Frontend and backend often need the same definition of an object or event.
+Shared code should usually contain contracts that are safe on both sides:
+
+```ts
+interface CreateRunRequest {
+  goal: string;
+  mode: "ask" | "plan" | "agent" | "debug" | "multitask";
+}
+
+interface CreateRunResponse {
+  id: string;
+  status: "queued" | "running";
+}
+```
+
+Shared code is usually a bad home for server secrets, database connections, or
+privileged runtime objects.
+
+## Server/worker entrypoints
+
+A runtime entrypoint is the first code the host invokes. A Worker might expose:
+
+```js
+export default {
+  fetch(request, env, ctx) {
+    return handleRequest(request, env, ctx);
+  }
+};
+```
+
+A maintainable architecture often keeps that adapter thin:
+
+```text
+runtime/worker entrypoint
+        -> application router
+        -> use case/business logic
+        -> database/provider adapters
+```
+
+The entrypoint connects the host runtime to the application. It does not need to
+contain the entire application.
+
+## Database and persistence
+
+State has to live somewhere. Ask how long it must survive and who must share it.
+
+Examples:
+
+```text
+React component state   survives a render/session as designed
+localStorage            stays in one browser/profile
+SQLite                   durable local process/application state
+Postgres/D1              shared durable application state
+object storage           files/blobs/large artifacts
+Git                      source-control history
+Merkle snapshots         evidence of filesystem state
+```
+
+Do not add a database if browser-local state satisfies the actual requirement.
+Do not use browser-local state for data that must be authoritative across users
+or machines.
+
+## Authentication vs authorization
+
+Authentication asks:
+
+> Who are you?
+
+Authorization asks:
+
+> Are you allowed to do this?
+
+A verified user ID on the backend is evidence for authentication. A policy or
+ownership check deciding whether that user can edit a project is authorization.
+
+Never trust a browser-supplied `user_id` merely because it is present in JSON.
+
+## WebSocket
+
+HTTP is naturally request/response. A WebSocket keeps a two-way connection open,
+which is useful for terminals, streaming events, multiplayer state, and other
+interactive flows.
+
+```text
+client <==========================> server
+       commands / output / events
+```
+
+Use it when the interaction actually benefits from a persistent two-way channel;
+do not reach for it when a normal HTTP request is simpler.
+
+## Service and microservice
+
+A service is a capability that runs behind an interface.
+
+A microservice is typically a relatively small service that can be deployed and
+operated independently. A folder called `services/` does not automatically make
+something a microservice.
+
+Before calling something a microservice, look for evidence such as:
+
+- independent runtime/process,
+- explicit network or message interface,
+- separate deployment lifecycle,
+- clear ownership boundary.
+
+## Package vs app vs service
+
+A useful distinction:
+
+```text
+package/library
+  reusable code imported by other code
+
+app/product
+  complete user-facing or operator-facing composition
+
+service
+  independently running capability accessed through an interface
+```
+
+A monorepo can contain all three.
+
+## End-to-end example
+
+Suppose the user clicks "Start agent":
+
+```text
+1. frontend button receives click
+2. frontend validates obvious input
+3. frontend POSTs /api/runs
+4. backend authenticates/authorizes request
+5. backend validates CreateRunRequest
+6. backend creates the authoritative run
+7. backend starts/schedules model/tool work
+8. backend returns run ID/status
+9. frontend subscribes/polls for updates
+10. UI renders running/completed/error state
+```
+
+The feature is not complete merely because step 1 and a spinner exist.

package/skills/agentsam-progression-guard/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: agentsam-progression-guard
+description: >
+  Turn application growth into explicit no-regression checkpoints across local work,
+  Git/PR CI, predeploy, deploy, postdeploy, and runtime operation. Use when adding a
+  feature/service/package, designing hooks or CI/CD, preparing a release, deciding what
+  should block a merge/deploy, implementing canary/rollback/feature-flag mechanics, or
+  proving a change is safer than the last promoted baseline. Triggers on "no regress",
+  "progression guard", "ship guard", "CI", "deploy hook", "pre-commit", "predeploy",
+  "postdeploy", "rollback", "canary", "feature flag", "release gate", and "promotion".
+metadata:
+  short-description: "Evidence gates and hook contracts that let a growing app progress without silently regressing"
+  aliases:
+    - progression-guard
+    - no-regress
+    - ship-guard
+    - release-guard
+user-invocable: true
+---
+
+# AgentSam Progression Guard
+
+The system should not depend on a developer remembering every rule in a million-line
+codebase. Put important invariants at lifecycle checkpoints and make promotion depend
+on evidence.
+
+## Core law
+
+**A state may be promoted only after the checks appropriate to that boundary pass. A
+failed candidate must not advance the last-known-good baseline.**
+
+This is the same principle whether the boundary is a commit, merge, deployment,
+feature rollout, schema migration, or service version.
+
+## Checkpoint chain
+
+```text
+intent/design
+  -> local edit loop
+  -> commit/push gate
+  -> clean CI / PR gate
+  -> predeploy evidence capture
+  -> deploy
+  -> postdeploy smoke + contract checks
+  -> promote baseline
+  -> runtime observe / canary / rollback
+```
+
+Do not run the heaviest possible suite at every keystroke. Use the dependency graph to
+make early gates fast and affected-only, then require broader proof at merge/release.
+
+Read `references/checkpoint-chain.md` for the detailed gate matrix.
+
+## Hooks are operational I/O contracts
+
+A hook is not "some script that happens to run." Every hook should have a small
+contract:
+
+```text
+Hook
+  event:
+  scope/affected graph:
+  immutable input refs:
+  allowed reads:
+  allowed writes/side effects:
+  credential scope:
+  command/handler:
+  timeout/retry:
+  output receipt:
+  failure policy: warn | block | rollback | quarantine
+```
+
+Prefer idempotent hooks when practical. Never give a hook broader credentials than the
+work it performs. Never let its output leak secret values. Never mark a deploy
+successful because the provider command returned zero if the required postdeploy
+checks have not run.
+
+Read `references/hooks-operational-io.md` for hook design and failure semantics.
+
+## AgentSam's existing proof chain
+
+Use the SDK mechanics as one coherent gate system rather than unrelated commands:
+
+```bash
+# Architecture/index/trust evidence
+agentsam inspect --json
+agentsam security scan --path .
+
+# Capture exact predeploy state and delta from the last promoted baseline
+agentsam deploy-receipt capture . --project <project> --json
+
+# Run the real provider deploy here
+# e.g. npm run deploy / wrangler deploy / project-specific release command
+
+# Only after required postdeploy checks succeed
+agentsam deploy-receipt success . --deployment-id <id> --worker-version <id> --json
+
+# If deploy or postdeploy verification fails
+agentsam deploy-receipt failure . --deployment-id <id> --json
+```
+
+A successful finalize advances the local promoted Merkle baseline. A failure preserves
+the previous trusted baseline. Keep provider deployment identity and AgentSam evidence
+identity together in the receipt when available.
+
+## What each layer should catch
+
+- **AST/index gate:** structural contradictions, dependency edges, execution-domain mistakes, contract ownership drift.
+- **Merkle gate:** exact before/after source identity and change scope.
+- **Security gate:** dependency advisories plus client/server trust-boundary contradictions.
+- **Type/schema gate:** compile-time and runtime contract drift.
+- **Test gate:** behavior regressions at unit/integration/end-to-end boundaries.
+- **Firewall/WAF/rate-limit gate:** hostile or abusive ingress patterns before application logic.
+- **Auth/authorization gate:** verified identity, scope, ownership, and privileged action rules inside the application.
+- **Deploy/postdeploy gate:** provider accepted the artifact *and* critical live behavior still works.
+- **Runtime gate:** error/latency/saturation/security signals after promotion.
+
+None of these replaces the others.
+
+## Package/service progression rule
+
+When a package/service changes:
+
+```text
+changed node
+  -> compute affected downstream nodes
+  -> run local affected checks
+  -> run clean CI for required contract/build/security coverage
+  -> deploy only the changed deployable units plus required dependents
+  -> smoke their public contracts
+  -> promote their evidence baseline
+```
+
+For a cross-service contract change, producers and consumers are one change set even
+if they live in separate packages/repositories. Use versioned schemas/contracts and
+consumer tests to make the coupling explicit.
+
+## Deployment safety ladder
+
+Not every app needs every rung on day one. Add protection as risk grows:
+
+```text
+single deploy + smoke test
+  -> automatic rollback on failed smoke
+  -> feature flag separating deploy from release
+  -> canary / small traffic cohort
+  -> metrics comparison window
+  -> gradual promotion
+```
+
+The point is not ceremony. The point is reducing blast radius and making the system
+prove health before widening exposure.
+
+## Regression rules
+
+1. Never advance a trusted baseline after a failed deploy or failed postdeploy check.
+2. Never let local success substitute for clean-environment CI on merge/release.
+3. Never make all hooks blocking; classify fast/blocking versus informational/async deliberately.
+4. Never make a pre-commit hook so expensive developers bypass it; move broad work to CI.
+5. Never let branch protection depend on checks that are not deterministic/reproducible enough to trust.
+6. Never deploy a breaking contract without proving affected consumers or a compatibility strategy.
+7. Never use a WAF rule as a substitute for application authorization.
+8. Never auto-rollback a database/schema change unless the data migration itself is designed and proven reversible; prefer forward-fix/expand-contract strategies where rollback would lose data.
+9. Never make feature flags permanent invisible architecture. Give them an owner and cleanup condition.
+10. Never call observability "monitoring later." Define the success/failure signal before promotion.
+
+## Completion receipt
+
+When acting as the release/build agent, finish with a compact receipt:
+
+```text
+Candidate
+  git/revision:
+  merkle root:
+  semantic metadata root:
+  affected packages/services:
+
+Gates
+  type/build:
+  tests:
+  contracts:
+  security:
+  deploy:
+  postdeploy:
+
+Promotion
+  provider deployment/version:
+  baseline advanced: yes/no
+  feature flag/canary state:
+  rollback/failure action:
+
+Open risks
+  ...
+```
+
+A human should be able to understand why this state was promoted without reading the
+entire CI log.

package/skills/agentsam-progression-guard/references/checkpoint-chain.md

@@ -0,0 +1,111 @@
+# Checkpoint Chain
+
+## Gate 0 — intent/design
+
+Before code, name the behavior, authority owner, boundary contracts, state owner, and
+credentialed destinations. For sensitive paths, name abuse/failure cases too.
+
+Evidence: short design/plan, relevant schema/type, destination card.
+
+## Gate 1 — local edit loop
+
+Goal: feedback in seconds.
+
+Prefer changed/affected scope:
+
+- syntax/lint;
+- TypeScript/type checking for affected packages;
+- narrow unit tests;
+- AST/index contradiction checks when boundaries changed;
+- secret scan for newly touched material.
+
+Do not run a 20-minute suite on every save.
+
+## Gate 2 — commit/push
+
+Goal: stop obvious bad states before remote review.
+
+Typical blocking checks:
+
+- formatting/lint/type sanity;
+- fast affected tests;
+- secret scanning;
+- generated-contract consistency if committed artifacts are expected.
+
+A pre-commit/push hook is local convenience and early protection. CI remains the
+shared authority because local hooks can be skipped or differ by machine.
+
+## Gate 3 — PR / clean CI
+
+Goal: prove the candidate from a clean environment.
+
+Typical required checks:
+
+- clean dependency install;
+- full/required build;
+- broader unit/integration tests;
+- contract/schema compatibility;
+- `agentsam security scan`;
+- deterministic repository/AST/Merkle evidence;
+- deployment dry run where supported.
+
+Use branch protection to make required checks real gates instead of reminders.
+
+## Gate 4 — predeploy
+
+Goal: tie the exact candidate to a reproducible evidence identity.
+
+Capture the Merkle/semantic snapshot and compare with the last promoted baseline.
+Confirm:
+
+- source tree/revision intended for deploy;
+- no unexplained trust-boundary contradictions;
+- required release checks green;
+- credentialed destinations/config are present without logging their secret values;
+- migration/deploy plan is understood.
+
+Use `agentsam deploy-receipt capture` immediately before the provider release command
+when practical.
+
+## Gate 5 — deploy
+
+Goal: perform the real side effect with the smallest necessary authority.
+
+Record provider deployment/version identity. Deployment success means the provider
+accepted the candidate; it does not yet prove user-visible health.
+
+## Gate 6 — postdeploy
+
+Goal: exercise critical live I/O.
+
+Examples:
+
+- health endpoint;
+- authentication callback/session creation;
+- one critical read/write path against non-destructive test data;
+- public asset/route availability;
+- service binding/RPC call;
+- external provider integration where a safe smoke path exists;
+- error/latency signals for the new version.
+
+Failure should block promotion and trigger the defined rollback/quarantine response.
+
+## Gate 7 — promote
+
+Only now advance the last-known-good evidence baseline. In AgentSam that means
+finalizing the deploy receipt as success. Failed deploy or failed smoke must finalize
+as failure and leave the trusted baseline untouched.
+
+## Gate 8 — runtime
+
+Continue observing after promotion. For higher-risk changes, use a canary cohort,
+feature flag, or gradual rollout so health can be compared before full exposure.
+
+Runtime signals should have owners and actions, not just dashboards:
+
+```text
+signal -> threshold/window -> action -> receipt/incident
+```
+
+Examples: error-rate spike -> disable feature flag; auth failures -> halt rollout;
+latency regression -> keep canary at current cohort and investigate.