palai

module
v0.0.0-...-5a20295 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 13, 2026 License: Apache-2.0

README

Palai

Palai is a provider-neutral, self-hostable agent execution platform. It exposes one durable execution kernel through Responses, Sessions, reusable Agents, and interoperability adapters.

The repository has completed its E01 technology baseline: executable spike reports select the implementation toolchain before production runtime work starts. This evidence accepts technology decisions only; it does not claim that the LP-0 local stack or a self-host release is complete.

Development

The reference toolchain is pinned in .tool-versions. Bootstrap and run the same foundation checks used by CI:

make bootstrap
make verify
bash scripts/verify/e01.sh

Provider credentials are not required for foundation checks. Never place a provider key in the repository, a command argument, or committed evidence; the local CLI will accept credentials through a write-only bootstrap path when the model-broker phase is available.

Documents

Initial delivery target

The first milestone is a complete local stack proven against a real model provider and consumed from a Next.js application through the TypeScript SDK. Managed SaaS product work is intentionally outside the current implementation plan.

License

Apache License 2.0. See LICENSE.

Directories

Path Synopsis
adapters
integrations/a2a
Package a2a is the A2A 1.0 (Agent2Agent) HTTP+JSON server projection (spec §38, E17 Task 2).
 Package a2a is the A2A 1.0 (Agent2Agent) HTTP+JSON server projection (spec §38, E17 Task 2).
integrations/mcp
Package mcp is the Palai MCP client (spec §28.13, MCP 2025-11-25).
 Package mcp is the Palai MCP client (spec §28.13, MCP 2025-11-25).
integrations/queue
Package queue is the queue-adapter contract (E17 Task 7, spec §34.1-34.5): a SQS/PubSub/Kafka-class durable consumer + an outbound result-delivery outbox, both following the SAME durable-delivery discipline the automation webhook/inbound seam already enforces (durable-record-before-ack, dedupe on an idempotency key, bounded-buffer backpressure, dead-letter after N failures).
 Package queue is the queue-adapter contract (E17 Task 7, spec §34.1-34.5): a SQS/PubSub/Kafka-class durable consumer + an outbound result-delivery outbox, both following the SAME durable-delivery discipline the automation webhook/inbound seam already enforces (durable-record-before-ack, dedupe on an idempotency key, bounded-buffer backpressure, dead-letter after N failures).
integrations/slack
integrations/webhook
Package webhook is the sole outbound-webhook integration adapter (dependency direction, plan §4: HTTP egress lives only here).
 Package webhook is the sole outbound-webhook integration adapter (dependency direction, plan §4: HTTP egress lives only here).
models/anthropic
Package anthropic is the anthropic (Anthropic) model adapter — a second, INDEPENDENT direct provider family at the same broker contract as openai.
 Package anthropic is the anthropic (Anthropic) model adapter — a second, INDEPENDENT direct provider family at the same broker contract as openai.
models/fake
Package fake is the deterministic model adapter behind the conformance and security suites.
 Package fake is the deterministic model adapter behind the conformance and security suites.
models/openai
Package openai is the openai (OpenAI) model adapter.
 Package openai is the openai (OpenAI) model adapter.
models/registry
Package registry builds the broker's adapter map from the canonical family list.
 Package registry builds the broker's adapter map from the canonical family list.
repositories
Package repositories owns the infrastructure side of the repository lifecycle: the deterministic, untrusted-repo-hardened preparation (spec §30.3), the untrusted-repo defenses (§30.4), and the scoped credential broker (§30.2, §28.11).
 Package repositories owns the infrastructure side of the repository lifecycle: the deterministic, untrusted-repo-hardened preparation (spec §30.3), the untrusted-repo defenses (§30.4), and the scoped credential broker (§30.2, §28.11).
sandboxes/host
Package host runs a workspace shell command DIRECTLY ON THIS MACHINE.
 Package host runs a workspace shell command DIRECTLY ON THIS MACHINE.
sandboxes/oci
Package oci runs a single untrusted engine attempt inside a hardened, digest-pinned OCI container and returns its raw, separately bounded stdout and stderr.
 Package oci runs a single untrusted engine attempt inside a hardened, digest-pinned OCI container and returns its raw, separately bounded stdout and stderr.
sandboxes/oci/snapshot
Package snapshot builds and restores the byte-archive of a workspace allocation (spec §29.10, E10 Task 6).
 Package snapshot builds and restores the byte-archive of a workspace allocation (spec §29.10, E10 Task 6).
sandboxes/oci/workspace
Package workspace lays out a physical workspace allocation on the runner host and computes a create-side snapshot of it.
 Package workspace lays out a physical workspace allocation on the runner host and computes a create-side snapshot of it.
sandboxes/posture
Package posture answers one question from the environment a process was started with: WHERE does a shell command run on this machine, and under WHAT BOUNDS.
 Package posture answers one question from the environment a process was started with: WHERE does a shell command run on this machine, and under WHAT BOUNDS.
tools/http
Package remotehttp is the remote-HTTP tool transport (spec §28.24-28.25, E12 Task 4): the broker's remote_http executor signs a tool-http.v1 invoke, POSTs it egress-safe to a customer tool server (a NEW trust boundary), and either returns the 200 result inline or opens a durable async operation a signed 202 callback later resolves.
 Package remotehttp is the remote-HTTP tool transport (spec §28.24-28.25, E12 Task 4): the broker's remote_http executor signs a tool-http.v1 invoke, POSTs it egress-safe to a customer tool server (a NEW trust boundary), and either returns the 200 result inline or opens a durable async operation a signed 202 callback later resolves.
apps
control-plane/api
Package api is the control-plane HTTP surface.
 Package api is the control-plane HTTP surface.
control-plane/api/middleware
Package middleware holds the control-plane HTTP plumbing: request context, bearer authentication, idempotency-key enforcement, and RFC 9457 problem rendering.
 Package middleware holds the control-plane HTTP plumbing: request context, bearer authentication, idempotency-key enforcement, and RFC 9457 problem rendering.
control-plane/cmd/palai-capability-worker command
Command palai-capability-worker is the macOS FIXTURE capability worker (E17 Task 9, spec §31, WRK-001..007).
 Command palai-capability-worker is the macOS FIXTURE capability worker (E17 Task 9, spec §31, WRK-001..007).
control-plane/cmd/palai-control-plane command
Command palai-control-plane serves the LP-0 HTTP surface over the durable spine.
 Command palai-control-plane serves the LP-0 HTTP surface over the durable spine.
control-plane/internal/artifacts
Package artifacts is the control-plane's boundary over the S3-compatible object store (SeaweedFS locally).
 Package artifacts is the control-plane's boundary over the S3-compatible object store (SeaweedFS locally).
control-plane/internal/automation
Package automation is the control-plane domain logic for the E11 automation layer.
 Package automation is the control-plane domain logic for the E11 automation layer.
control-plane/internal/botcreds
Package botcreds joins two inventories that deliberately know nothing about each other: the kind-agnostic bot registry (internal/bots, whose charter is that no method of its own decodes a bot's `config`) and the secret store (internal/identity, whose charter is that a sealed value has no read-back path).
 Package botcreds joins two inventories that deliberately know nothing about each other: the kind-agnostic bot registry (internal/bots, whose charter is that no method of its own decodes a bot's `config`) and the secret store (internal/identity, whose charter is that a sealed value has no read-back path).
control-plane/internal/bots
Package bots is the kind-agnostic bot registry (migration 000061, 2026-08-03 plan Task 4): a project's registered bots, one row per relay process the console can create.
 Package bots is the kind-agnostic bot registry (migration 000061, 2026-08-03 plan Task 4): a project's registered bots, one row per relay process the console can create.
control-plane/internal/execution
Package execution's orchestrator is the single response kernel: it drives a run through the canonical state machine and a live engine channel, committing every provider and tool result before it reaches the engine.
 Package execution's orchestrator is the single response kernel: it drives a run through the canonical state machine and a live engine channel, committing every provider and tool result before it reaches the engine.
control-plane/internal/execution/tools
Package tools defines the built-in model-facing tool surface (file, shell) that runs behind the sandbox-backed execution seam (spec §28.7-28.8).
 Package tools defines the built-in model-facing tool surface (file, shell) that runs behind the sandbox-backed execution seam (spec §28.7-28.8).
control-plane/internal/extensions
Package extensions is the control-plane domain logic for the E12 extensibility registry.
 Package extensions is the control-plane domain logic for the E12 extensibility registry.
control-plane/internal/fleet
Package fleet is the runner registry: which machines have enrolled, under which pool, holding which certificate, and when each was last seen.
 Package fleet is the runner registry: which machines have enrolled, under which pool, holding which certificate, and when each was last seen.
control-plane/internal/identity
This file adds the ENVIRONMENT surface to the identity package (E25 T3): a named group of key→value pairs an agent's shell receives.
 This file adds the ENVIRONMENT surface to the identity package (E25 T3): a named group of key→value pairs an agent's shell receives.
control-plane/internal/knowledge
Package knowledge is the E17 Task 4 knowledge spine (17b): an IMMUTABLE ingestion -> index -> retrieval spine on PostgreSQL full-text search (tsvector/tsquery + GIN, migration 000035 in-tree — assigned 000036, renumbered at merge per the fixed order; see the migration's MERGE NOTE).
 Package knowledge is the E17 Task 4 knowledge spine (17b): an IMMUTABLE ingestion -> index -> retrieval spine on PostgreSQL full-text search (tsvector/tsquery + GIN, migration 000035 in-tree — assigned 000036, renumbered at merge per the fixed order; see the migration's MERGE NOTE).
control-plane/internal/metering
Package metering is the durable store behind the usage surface (spec §43, E13 Task 6, BIL-001/BIL-003/QUO-001): the read half of the append-only usage_ledger, and the write half of the budgets/quotas limits the ADMISSION transaction enforces.
 Package metering is the durable store behind the usage surface (spec §43, E13 Task 6, BIL-001/BIL-003/QUO-001): the read half of the append-only usage_ledger, and the write half of the budgets/quotas limits the ADMISSION transaction enforces.
control-plane/internal/metrics
Package metrics exposes the control plane's operational signals in Prometheus text-exposition format on an unauthenticated, internal-network GET /metrics (mounted beside /healthz — the production edge path-matches `reverse_proxy /v1/*` in deploy/compose/production.yml, so it never proxies this; Prometheus reaches it on the internal Compose network).
 Package metrics exposes the control plane's operational signals in Prometheus text-exposition format on an unauthenticated, internal-network GET /metrics (mounted beside /healthz — the production edge path-matches `reverse_proxy /v1/*` in deploy/compose/production.yml, so it never proxies this; Prometheus reaches it on the internal Compose network).
control-plane/internal/store
Journal reads the durable session journal for the control-plane's live event stream.
 Journal reads the durable session journal for the control-plane's live event stream.
control-plane/internal/workers
Package workers is the CapabilityWorker contract (spec §31.2-31.6, E17 Task 9, WRK-001..007): the outbound-enrolled, lease/fenced execution surface for typed CAPABILITY jobs that run OUTSIDE the control plane's process/network — the same enrollment + lease/fencing semantics a runner uses (packages/runner + coordinator), applied to a macOS host toolchain the container cannot reach.
 Package workers is the CapabilityWorker contract (spec §31.2-31.6, E17 Task 9, WRK-001..007): the outbound-enrolled, lease/fenced execution surface for typed CAPABILITY jobs that run OUTSIDE the control plane's process/network — the same enrollment + lease/fencing semantics a runner uses (packages/runner + coordinator), applied to a macOS host toolchain the container cannot reach.
control-plane/internal/workspacestore
Package workspacestore is the control plane's half of the workspace inversion: the object-store layout a workspace is published into, and the durable head that says which manifest it is at.
 Package workspacestore is the control plane's half of the workspace inversion: the object-store layout a workspace is published into, and the durable head that says which manifest it is at.
slack-bot command
Command slack-bot is a Palai bot process: one instance per registered row in the control plane's bot registry (POST/GET /v1/bots, apps/control-plane/api/bots.go).
 Command slack-bot is a Palai bot process: one instance per registered row in the control plane's bot registry (POST/GET /v1/bots, apps/control-plane/api/bots.go).
slack-bot/internal/config
Package config loads the slack-bot process's environment.
 Package config loads the slack-bot process's environment.
slack-bot/internal/relay
This file is Task 10 (2026-08-03 plan): the approval bridge.
 This file is Task 10 (2026-08-03 plan): the approval bridge.
slack-bot/internal/socket
Package socket is the slack-bot's Socket Mode connect loop (2026-08-03 plan, Task 12.5): the one piece of genuinely new code the wiring task needed, because every other piece already existed and only lacked a caller.
 Package socket is the slack-bot's Socket Mode connect loop (2026-08-03 plan, Task 12.5): the one piece of genuinely new code the wiring task needed, because every other piece already existed and only lacked a caller.
slack-bot/internal/store
Package store is the slack-bot's own durable state: the mapping from a Slack thread to a Palai session (2026-08-03 plan, Task 8).
 Package store is the slack-bot's own durable state: the mapping from a Slack thread to a Palai session (2026-08-03 plan, Task 8).
slack-bot/migrations
Package migrations embeds the slack-bot's own forward-only schema — one small table so far (thread_sessions, Task 8) — kept separate from storage.OrderedMigrations (storage/migrations.go) because the two are unrelated schemas: this one lives in the bot's own database, has no down files (nothing here has ever needed a rollback), and versions from 1, not from wherever storage's chain happens to be.
 Package migrations embeds the slack-bot's own forward-only schema — one small table so far (thread_sessions, Task 8) — kept separate from storage.OrderedMigrations (storage/migrations.go) because the two are unrelated schemas: this one lives in the bot's own database, has no down files (nothing here has ever needed a rollback), and versions from 1, not from wherever storage's chain happens to be.
cmd
cli command
Command palai is the local-stack CLI: it initialises the .palai layout, drives the four-service Docker Compose distribution, runs the doctor health surface, stores provider credentials, and admits responses over the bootstrap key.
 Command palai is the local-stack CLI: it initialises the .palai layout, drives the four-service Docker Compose distribution, runs the doctor health surface, stores provider credentials, and admits responses over the bootstrap key.
cli/internal/stack
Package stack implements the `palai` local-stack lifecycle: it initialises the .palai data layout, drives the four-service Docker Compose distribution up and down, and runs the doctor health surface.
 Package stack implements the `palai` local-stack lifecycle: it initialises the .palai data layout, drives the four-service Docker Compose distribution up and down, and runs the doctor health surface.
palai-toolbroker command
Command palai-toolbroker serves one allocation's brokered toolchain.
 Command palai-toolbroker serves one allocation's brokered toolchain.
palai-toolshim command
Command palai-toolshim is `xcodebuild` and `simctl` as far as a sandboxed session can tell.
 Command palai-toolshim is `xcodebuild` and `simctl` as far as a sandboxed session can tell.
runner command
Command runner is the Palai private execution host.
 Command runner is the Palai private execution host.
deploy
compose
packages
audit
Package audit is the SEC-103 audit-integrity chain (E18 T7; it closes the E13-H "audit integrity linkage" debt).
 Package audit is the SEC-103 audit-integrity chain (E18 T7; it closes the E13-H "audit integrity linkage" debt).
contracts
Code generated from the canonical Agent schema; DO NOT EDIT.
 Code generated from the canonical Agent schema; DO NOT EDIT.
coordinator
Package coordinator is the durable job engine for the Palai control plane (spec §24.4).
 Package coordinator is the durable job engine for the Palai control plane (spec §24.4).
coordinator/recovery
Package recovery persists the durable recovery objects (spec §26.1-26.2): the engine checkpoint metadata and its shared transcript boundary, written as SEPARATE immutable rows.
 Package recovery persists the durable recovery objects (spec §26.1-26.2): the engine checkpoint metadata and its shared transcript boundary, written as SEPARATE immutable rows.
device
Package device holds the one-time INSTALL half of a Palai agent: where a machine keeps its configuration and its durable identity, how both are written so no other account can read them, and how the service that runs the agent is registered with the platform.
 Package device holds the one-time INSTALL half of a Palai agent: where a machine keeps its configuration and its durable identity, how both are written so no other account can read them, and how the service that runs the agent is registered with the platform.
egress
Package egress is the shared SSRF-defense layer every outbound-HTTP caller vets through: the webhook sender, the web-research tool, and (later) the remote HTTP + MCP transports.
 Package egress is the shared SSRF-defense layer every outbound-HTTP caller vets through: the webhook sender, the web-research tool, and (later) the remote HTTP + MCP transports.
extension-sdk
Package extsdk is the server-side helper set for building a remote_http tool endpoint that speaks tool-http.v1 (spec §28.23/§28.24, TOL-018).
 Package extsdk is the server-side helper set for building a remote_http tool endpoint that speaks tool-http.v1 (spec §28.23/§28.24, TOL-018).
localca
Package localca mints the trust root a self-hosted control plane serves its runner gateway with: one local CA and one gateway server certificate.
 Package localca mints the trust root a self-hosted control plane serves its runner gateway with: one local CA and one gateway server certificate.
model-broker
Package modelbroker routes a canonical model request to a provider adapter and returns a canonical result.
 Package modelbroker routes a canonical model request to a provider adapter and returns a canonical result.
outputcontract
Package outputcontract owns the run's OUTPUT CONTRACT: the `output` field of a response-create request (spec §8.2, §22.7), the safety checks that decide whether a schema may be accepted at all, and the validation of a finished run's answer against it.
 Package outputcontract owns the run's OUTPUT CONTRACT: the `output` field of a response-create request (spec §8.2, §22.7), the safety checks that decide whether a schema may be accepted at all, and the validation of a finished run's answer against it.
pricing
Package pricing is the RATE that turns consumption into money — never the consumption itself.
 Package pricing is the RATE that turns consumption into money — never the consumption itself.
runner
state-machines
Package statemachines holds the pure, in-memory state transition tables and guards for Palai execution resources.
 Package statemachines holds the pure, in-memory state transition tables and guards for Palai execution resources.
tool-broker
Package toolbroker executes pure, in-process conformance tools behind fenced tool-call rows (spec §26.7).
 Package toolbroker executes pure, in-process conformance tools behind fenced tool-call rows (spec §26.7).
toolset
Package toolset is the CANONICAL list of tools a palai bring-up grants.
 Package toolset is the CANONICAL list of tools a palai bring-up grants.
version
Package version is the single build-version stamp source shared by the control-plane, the runner, and the CLI.
 Package version is the single build-version stamp source shared by the control-plane, the runner, and the CLI.
workspacestore
Package workspacestore holds the value types a workspace is published and materialised through: a content-addressed blob per file, and a manifest that names the WHOLE state at one instant.
 Package workspacestore holds the value types a workspace is published and materialised through: a content-addressed blob per file, and a manifest that names the WHOLE state at one instant.
scripts
contracts/generator command
Command generator promotes canonical JSON Schema contracts into the per-language sources under packages/contracts and protocols/generated.
 Command generator promotes canonical JSON Schema contracts into the per-language sources under packages/contracts and protocols/generated.
contracts/semantic command
Command semantic derives the OpenAPI 3.1.2 compatibility projection from the canonical 3.2 document and verifies the two are semantically equivalent.
 Command semantic derives the OpenAPI 3.1.2 compatibility projection from the canonical 3.2 document and verifies the two are semantically equivalent.
sdks
go module
spikes
cmd/report-check command
contracts
contracts/cmd/candidate-check command
contracts/cmd/report command
contracts/generated/go
Code generated from the canonical Fixture schema; DO NOT EDIT.
 Code generated from the canonical Fixture schema; DO NOT EDIT.
contracts/generator command
control-plane/go-server command
control-plane/load command
fsevents command
This spike drives the REAL FSEvents API, so it exists only where that API exists.
 This spike drives the REAL FSEvents API, so it exists only where that API exists.
internal/report
nextjs-streaming/cmd/report command
object-store
object-store/cmd/offline-load command
object-store/cmd/report command
postgres-coordinator
postgres-coordinator/cmd/report command
runner
runner/cmd/report command
runner/engine command
Package storage embeds the canonical SQL migrations and queries for the durable execution spine and opens tenant-scoped connection pools against them.
 Package storage embeds the canonical SQL migrations and queries for the durable execution spine and opens tenant-scoped connection pools against them.
tests
evals
Package evals is the E17 T6 eval harness: a content-addressed fixture format + a deterministic Go runner that scores four suites (coding, research/citation, recovery, security/red-team) and feeds a release gate.
 Package evals is the E17 T6 eval harness: a content-addressed fixture format + a deterministic Go runner that scores four suites (coding, research/citation, recovery, security/red-team) and feeds a release gate.
performance
Package performance is the E18 Task 6 performance harness (PER-001..004, spec §54.3, §64.14).
 Package performance is the E18 Task 6 performance harness (PER-001..004, spec §54.3, §64.14).
sandboxes/engine command
Command engine is the fixture engine image the runner Docker suites supervise.
 Command engine is the fixture engine image the runner Docker suites supervise.
sandboxes/mcp command
Command mcp-fixture is a minimal, newline-delimited JSON-RPC MCP server (2025-11-25 stdio framing) used ONLY by the E12 Task 5 test tiers.
 Command mcp-fixture is a minimal, newline-delimited JSON-RPC MCP server (2025-11-25 stdio framing) used ONLY by the E12 Task 5 test tiers.
uat
Package uat holds the local-live UAT case runner and the evidence verifier.
 Package uat holds the local-live UAT case runner and the evidence verifier.
uat/cmd/evidence-verify command
Command evidence-verify checks a local-live evidence bundle against the manifest contract (required receipts present, exactly-one terminal per case, checksums well formed, no leaked credential) and prints the operator summary.
 Command evidence-verify checks a local-live evidence bundle against the manifest contract (required receipts present, exactly-one terminal per case, checksums well formed, no leaked credential) and prints the operator summary.
uat/cmd/promote command
Command promote is the mechanical SH-2 promote gate (plan §7): a release cannot be tagged/promoted unless its evidence bundle verifies clean AND carries a rollback proof + a restore/DR proof.
 Command promote is the mechanical SH-2 promote gate (plan §7): a release cannot be tagged/promoted unless its evidence bundle verifies clean AND carries a rollback proof + a restore/DR proof.
uat/dr
Package dr holds the E15 T5 disaster-recovery drill harness and its measurement/report logic.
 Package dr holds the E15 T5 disaster-recovery drill harness and its measurement/report logic.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.