@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/skills/agentsam-app-fundamentals/references/trust-credentials-and-destinations.md

@@ -0,0 +1,99 @@
+# Trust, Credentials, and Credentialed Destinations
+
+## Trust is about execution ownership
+
+The useful distinction is not "frontend equals UI" and "backend equals logic."
+The useful distinction is who controls execution.
+
+A browser, mobile client, or other user-controlled runtime can be inspected and
+modified by that user. Treat requests from it as claims that the trusted side must
+validate. Server-owned runtimes can hold privileged credentials and enforce durable
+invariants, but they still must authenticate callers and apply least privilege.
+
+## Public identifiers versus credentials
+
+A public client/application ID tells a provider **which registered application** is
+participating. It is often visible in redirect URLs or client configuration and is
+not, by itself, proof of authority.
+
+A client secret, API key, signing key, refresh token, database credential, or similar
+secret is authority-bearing material. Its value belongs only in the runtime that is
+allowed to use that authority. Do not confuse a secret's environment variable name
+with the secret itself.
+
+## OAuth redirect mental model
+
+Keep the endpoints separate:
+
+```text
+/app/auth/login
+  -> creates state / PKCE material as appropriate
+  -> redirects browser to provider authorization endpoint
+
+provider
+  -> authenticates user + consent
+  -> redirects only to registered callback
+
+/app/auth/callback
+  -> verifies state and flow binding
+  -> exchanges code server-to-server when the flow requires it
+  -> validates provider identity claims
+  -> finds/creates local user
+  -> establishes the app's own session
+  -> redirects to the intended in-app destination
+```
+
+The callback is not the user's final product page. It is a security-sensitive
+boundary where the external authorization flow becomes an internal authenticated
+session.
+
+For clients that cannot safely keep a static secret, use the provider's supported
+public-client flow such as Authorization Code + PKCE rather than embedding a secret
+in the client.
+
+## Destination registry mindset
+
+Treat every external system as a typed destination rather than an ad-hoc URL string.
+For each destination record:
+
+- canonical provider/service identity;
+- allowed host/origin and transport;
+- caller execution domain;
+- public IDs versus secret credentials;
+- scopes/permissions;
+- redirect/callback/webhook endpoints;
+- input/output schemas;
+- retry, timeout, idempotency, and rate-limit behavior;
+- audit/logging rules that never emit secrets;
+- rotation/revocation owner.
+
+This is the mechanism that makes `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, a
+callback URI, and a login route understandable as one relationship instead of four
+unrelated strings.
+
+## Defense in depth
+
+Think in layers, each assuming the layer before it can fail:
+
+```text
+internet
+  -> edge/DDoS protection
+  -> firewall/WAF/bot/rate-limit policy
+  -> route/authentication
+  -> authorization + ownership validation
+  -> runtime schema validation
+  -> least-privilege credential/service access
+  -> durable audit/observability
+```
+
+A WAF can reject known-bad traffic, but it cannot know your business ownership rule.
+Authentication can prove a user identity, but it does not automatically prove that
+user may modify a particular record. A valid credential can authenticate a service
+while still being over-privileged. Re-verify at each boundary.
+
+## Fail fast at configuration boundaries
+
+Validate required runtime configuration when the process/worker starts or before the
+first privileged operation. Check presence, expected public/secret classification,
+allowed destination, and format where the provider defines one. Never log the secret
+value to explain a validation failure.

package/skills/agentsam-cloudflare-workers/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: agentsam-cloudflare-workers
+description: >
+  Treat Cloudflare Workers, Wrangler, Durable Objects, D1, R2, Queues, Hyperdrive,
+  Browser, Containers, observability, versions, and deployment mechanics as a native
+  AgentSam execution dialect. Use when inspecting, debugging, profiling, operating,
+  or shipping Cloudflare-backed applications. Prefer typed Wrangler operations,
+  machine-readable output, explicit risk classes, real error/trace identifiers, and
+  Worker-runtime semantics over generic shell guessing.
+metadata:
+  short-description: "Cloudflare Workers/Wrangler native operations, observability, errors, and CPU discipline"
+  aliases:
+    - cloudflare
+    - workers
+    - wrangler
+    - cf-native
+user-invocable: true
+---
+
+# AgentSam Cloudflare Workers
+
+Cloudflare is a first-class execution environment, not just a deploy target. Use its
+runtime rules and Wrangler command contracts as native vocabulary.
+
+## Operating laws
+
+- Prefer structured Wrangler output such as `whoami --json`, deployments/versions JSON, and JSON tail events where supported.
+- Never ask a model to read or print `wrangler auth token`, API tokens, secrets, cookies, or credential files. Identity status is useful evidence; credential bytes are not.
+- Classify every operation before execution: read, local-runtime, filesystem-write, remote-write, secret-bearing, or long-running stream.
+- Keep `cwd`, account authority, connection identity, and execution leases runtime-owned. Do not accept them from model arguments when they are security-relevant.
+- Preserve real provider/runtime errors: process exit code, HTTP status, machine error type/code, request/Ray IDs, retry metadata, and bounded redacted stderr/body.
+- Do not infer CPU time from `performance.now()` or `Date.now()` around pure computation in a deployed Worker. Production timers advance around I/O; use local workerd/DevTools CPU profiles and production CPU metrics.
+- For expensive CPU investigations, collect a bounded profile summary and selected source evidence first, then hand that packet to the chosen reasoning model. Do not dump the repository or raw multi-megabyte profile into model context.
+- Prefer Web Crypto/native runtime primitives for CPU-intensive cryptography instead of pure-JavaScript reimplementations where the Worker contract allows it.
+- Remember that open TCP sockets have runtime and Durable Object lifecycle/cost implications; close them deliberately and prefer platform-native database connectivity such as Hyperdrive where appropriate.
+
+## Native workflow
+
+```text
+identify worker/config
+  -> verify Cloudflare identity without exposing token
+  -> inspect deployments/versions/config/types
+  -> reproduce locally with wrangler dev/workerd
+  -> collect JSON logs / CPU profile / production metrics
+  -> normalize errors and trace IDs
+  -> select only implicated source evidence
+  -> deterministic summary
+  -> optional high-reasoning model audit
+  -> verify locally
+  -> deploy only through the normal progression guard
+```
+
+Read the references for command risk classes, error envelopes, and CPU/observability mechanics.

package/skills/agentsam-cloudflare-workers/references/cpu-profiling.md

@@ -0,0 +1,16 @@
+# Worker CPU profiling
+
+A deployed Worker's `performance.now()` and `Date.now()` do not measure pure CPU loops reliably because the clock advances around I/O rather than ordinary CPU execution. Never create fake production CPU timings from those APIs.
+
+For CPU work:
+
+1. Reproduce with `wrangler dev`/workerd using production-like routes, request volume, and data/bindings where safe.
+2. Open DevTools from the Wrangler session and record a CPU profile.
+3. Export the `.cpuprofile` and run `agentsam cloudflare cpu analyze <profile.cpuprofile>`.
+4. Use the ranked self-time frames to select a small source slice.
+5. Optionally hand the bounded profile + selected source packet to a high-reasoning model through `cloudflare.cpu.audit`.
+6. Verify the fix locally, then compare production CPU metrics/error rate after normal deployment gates.
+
+Pay attention to garbage collection as well as application frames. Large allocation churn can be the hotspot even when no single application function looks dominant.
+
+Use native implementations when they remove JavaScript CPU work. For example, Worker Web Crypto operations are preferable to CPU-heavy pure-JavaScript cryptography when compatible with the required algorithm and contract.

package/skills/agentsam-cloudflare-workers/references/errors-and-observability.md

@@ -0,0 +1,29 @@
+# Cloudflare errors and observability
+
+## Error evidence contract
+
+When an operation fails, retain the most specific machine evidence available:
+
+```text
+source/provider
+operation
+process exit code or HTTP status
+machine error type
+machine error code
+request id / cf-ray when present
+retry-after and retry classification
+requested vs resolved processing/runtime mode when relevant
+bounded redacted response body or stderr
+```
+
+Do not flatten this to `request failed`, `429`, `500`, or `Wrangler failed` when richer evidence exists.
+
+## Retry discipline
+
+Retry only failures that can plausibly recover without changing operator state. Rate limits, ramp-rate throttles, overload, and transient provider 5xx errors may be retryable. Authentication, invalid arguments, billing/spend limits, unsupported regions, and missing permissions require configuration or operator action instead of retry loops.
+
+## Worker telemetry
+
+Use production Workers metrics/logs/traces for live evidence. Tail Workers and diagnostics channels can carry structured diagnostic events, but observability itself consumes resources and should remain bounded. Prefer structured fields and stable trace/request IDs over giant free-form logs.
+
+Unhandled promise rejections are runtime evidence and should be surfaced with the rejection reason/trace while redacting secrets.

package/skills/agentsam-cloudflare-workers/references/wrangler-native-map.md

@@ -0,0 +1,28 @@
+# Wrangler native map
+
+Treat Wrangler commands as typed operations rather than arbitrary shell text.
+
+## Safe model-visible reads
+
+AgentSam's initial native executor intentionally exposes only:
+
+- `whoami --json`
+- `deployments list --json`
+- `versions list --json`
+- `types --check`
+- `queues list`
+
+These are argv-built and cwd/config scoped. The allowlist is intentionally smaller than Wrangler's full command surface.
+
+## Known operational families
+
+- Identity/config: `whoami`, `auth list`, `auth activate`, `login`.
+- Development: `dev`, `types`, local persistence, remote bindings.
+- Observability: `tail`, deployments, versions, logs/traces/metrics.
+- Delivery: `deploy`, version deployment, rollback, triggers.
+- Data: D1, R2, KV, Queues, Hyperdrive, Vectorize.
+- Compute/AI: Containers, Browser, Workers AI, Workflows and related products.
+
+Remote mutation, rollback, secret handling, token retrieval, data writes, and long-running streams require a dedicated policy/approval path. Do not broaden the safe executor by passing arbitrary trailing argv.
+
+Wrangler global controls such as `--config`, `--cwd`, `--env`, and `--profile` are useful scoping mechanics. Keep them explicit; do not silently switch accounts or environments.

package/skills/agentsam-jr-dev/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: agentsam-jr-dev
+description: >
+  Teach, inspect, build, and revise software in junior-developer-friendly language
+  without replacing real engineering with toy explanations. Use when a user asks
+  what code, HTTP, frontend/backend, APIs, databases, auth, services, workers,
+  repositories, packages, deployments, or application architecture mean; when
+  onboarding someone to an unfamiliar repo; or when explaining why a proposed
+  implementation belongs in a particular layer. Also use while building or
+  reviewing software when the user benefits from understanding the real mechanics.
+  Triggers on "jr dev", "junior dev", "explain this", "what is HTTP", "frontend",
+  "backend", "API", "service", "microservice", "how does this app work", "repo map",
+  "teach me", "break this down", and "why does this go here".
+metadata:
+  short-description: "Teach real software mechanics from the actual repo, then prove the implementation"
+  aliases:
+    - agentsam_jr_dev
+    - jr-dev
+user-invocable: true
+---
+
+# AgentSam Jr Dev
+
+Teach software by connecting **simple mental models to the actual system in front
+of you**. The goal is not to make engineering sound easy. The goal is to make
+real engineering understandable without hiding the mechanics.
+
+A successful Jr Dev answer leaves the user knowing:
+
+1. **what the thing is,**
+2. **why it exists,**
+3. **where it lives in this project,**
+4. **what talks to it,**
+5. **what state or authority it owns,** and
+6. **how to prove it works.**
+
+Do not teach a fake generic architecture when repository evidence is available.
+Inspect first, then explain what is actually there.
+
+## Core behavior
+
+### 1. Start with the smallest useful explanation
+
+Use this progression unless the user asks for a different depth:
+
+- **10-second model** — one plain-language sentence.
+- **mechanics** — the actual request/data/control flow.
+- **repo proof** — name the real files, directories, routes, schemas, or services.
+- **engineering consequence** — explain why the boundary matters when building or changing it.
+
+Example:
+
+> HTTP is the agreed request/response language two programs use to talk over a
+> network. In this repo, the browser calls `/api/models`; the backend route
+> receives that request, uses trusted server-side configuration, and returns a
+> response the frontend can render.
+
+Never stop at an analogy when the user needs the real mechanism.
+
+### 2. Inspect before teaching repo-specific facts
+
+For an unfamiliar project, establish the system shape before making claims:
+
+- project/package manifests,
+- top-level tree,
+- runtime entrypoints,
+- frontend entrypoint and routes,
+- backend/server/worker entrypoint,
+- shared contracts,
+- API/transport boundaries,
+- persistence/storage,
+- auth/identity,
+- environment/config,
+- tests,
+- deployment/runtime configuration.
+
+Prefer deterministic repository/index/search tools over reading giant trees or
+hundreds of files into context. Read the smallest relevant spans that prove the
+explanation.
+
+### 3. Teach boundaries as ownership
+
+When explaining architecture, answer **who owns what**:
+
+- frontend owns presentation and browser interaction,
+- backend owns trusted execution and privileged access,
+- shared/contracts own the shape both sides agree on,
+- database/storage owns durable state,
+- auth owns verified identity,
+- HTTP/RPC/WebSocket is transport, not business logic,
+- workers/servers are runtime entrypoints, not automatically the whole backend,
+- packages expose reusable capabilities,
+- apps compose those capabilities into complete products,
+- services are independently running capabilities with explicit interfaces.
+
+Do not teach folder names as universal laws. A repo may call these layers
+`client/server`, `web/api`, `ui/core`, `worker`, or something else. Explain the
+**responsibility** first, then map it to this repo's names.
+
+Read `references/web-application-fundamentals.md` for the canonical beginner
+mental models and request-flow examples.
+
+### 4. Real application logic is the standard
+
+A polished screen is not proof of a working application. For any build/revision,
+trace the behavior end-to-end:
+
+```text
+user intent
+  -> UI/input
+  -> validated action/request
+  -> trusted business logic
+  -> state/storage/provider side effect
+  -> response/event
+  -> UI state update
+  -> verification
+```
+
+If the requested feature crosses layers, implement and verify every required
+layer. Do not hide missing backend/storage/auth/integration work behind mocked
+frontend state unless the user explicitly asked for a prototype.
+
+Read `references/real-application-logic.md` before claiming a new application,
+service, or cross-layer feature is complete.
+
+### 5. Explain changes in terms of consequences
+
+Instead of:
+
+> I moved this into the backend because that's cleaner.
+
+Prefer:
+
+> This operation needs a secret and writes durable state, so the browser cannot
+> be its authority. The frontend sends the user's intent; the backend verifies
+> it and performs the write. That keeps the secret off the client and gives us
+> one trusted place to enforce validation.
+
+Teach *why*, not just style conventions.
+
+## No-bullshit rules
+
+1. **Never invent a repo architecture.** Inspect it.
+2. **Never call a mock or static screen a finished application** unless the user asked for a mock/prototype.
+3. **Never claim an API/database/service works without exercising its real path** when tools allow verification.
+4. **Never add auth, a database, queues, microservices, or cloud infrastructure just to look production-grade.** Add them when the behavior requires them.
+5. **Never dump huge framework vocabulary before the user has a mental model.** Introduce terms when they explain a real observed mechanism.
+6. **Never equate HTTP with "the backend."** HTTP is one transport. The backend is the trusted logic/runtime behind the interface.
+7. **Never equate a Worker/server file with all business logic.** Prefer thin runtime adapters and explicit application/domain modules when the project warrants it.
+8. **Never teach frontend/backend as a security boundary without checking deployment reality.** Server-side code, browser bundles, secrets, and trust must be verified from the actual framework/runtime.
+9. **Never replace evidence with confidence.** Point to the file, route, schema, test, command, or result that proves the statement.
+10. **Never make "junior" mean patronizing.** Use plain language while preserving the real technical model.
+
+## Repo explanation template
+
+When someone asks "how does this repo/app work?", prefer a compact map like:
+
+```text
+Product
+  what a user can do
+
+Frontend
+  entrypoint:
+  routes/views:
+  state:
+  calls out to:
+
+Backend
+  runtime entrypoint:
+  API/actions:
+  trusted integrations:
+
+Shared contracts
+  types/schemas/events:
+
+State
+  browser-local:
+  durable database/storage:
+
+External systems
+  model providers / Git / payments / etc.:
+
+Request flow
+  user -> frontend -> transport -> backend -> state/provider -> response -> UI
+
+Proof
+  tests / health checks / real execution path:
+```
+
+Only include sections the actual project has.
+
+## Build/revision workflow
+
+For a real task:
+
+1. Restate the user-visible behavior in one sentence.
+2. Identify current architecture from repository evidence.
+3. Identify the authority/state owner for the behavior.
+4. Trace the end-to-end flow before editing.
+5. Reuse existing project patterns/contracts where sound.
+6. Make the smallest coherent cross-layer change.
+7. Exercise the real path.
+8. Explain the result at the user's requested depth.
+
+When debugging, teach the failing boundary:
+
+```text
+input -> frontend -> transport -> backend -> dependency -> persistence -> response
+```
+
+Find the first point where expected and actual behavior diverge.
+
+## Teaching vocabulary
+
+Prefer plain term -> precise term:
+
+- "the browser screen" -> frontend/client
+- "the trusted code doing the work" -> backend/server
+- "the agreed message shape" -> contract/schema
+- "the request language" -> HTTP
+- "a named HTTP endpoint" -> API route/endpoint
+- "long-lived two-way connection" -> WebSocket
+- "saved state" -> persistence/database/storage
+- "proof of who the user is" -> authentication
+- "what that user is allowed to do" -> authorization
+- "a separately running capability" -> service
+- "a small independently deployed service" -> microservice, only when it actually is one
+- "the program's starting door" -> entrypoint
+- "code reused by multiple products" -> package/library
+
+Introduce the precise term immediately after the plain one so the user learns the
+real vocabulary rather than remaining dependent on analogies.

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.