8000 feat(run): add durable Run protocol by Fodesu · Pull Request #83 · felinics/twilight · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 104 additions & 0 deletions agentcore/run/canonical/digest.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
package canonical

import (
"errors"
"fmt"

"github.com/felinics/twilight/agentcore/jsonstable"
"github.com/felinics/twilight/agentcore/run"
"github.com/felinics/twilight/agentcore/run/model"
)

// Envelope types of the bodies facts name by digest only (RUN-WIR-4). The
// frozen store (agent/run/frozen) keeps each body as the typed envelope its
// digest was computed from, so it encodes and decodes under the same names.
const (
RequestType = "model_request"
ModelResultType = "model_result"
ToolOutputType = "tool_output"
ToolResponseType = "tool_response_payload"
)

// preimageVersion is the version every digest preimage of this package
// carries in its domain separator. It is part of the persisted digests and
// never changes; a new digest rule would be a new domain, not a new number.
const preimageVersion uint16 = 1

// Digests is the digest rules of every body a fact names.
type Digests struct{}

func (Digests) DigestRequest(req model.ModelRequest) (run.Digest, error) { //nolint:gocritic // hugeParam: digest covers the complete immutable ModelRequest value.
body, err := jsonstable.EncodeTypedPayload(preimageVersion, RequestType, req)
if err != nil {
return "", err
}
return jsonstable.DigestBytes(body), nil
}

func (Digests) DigestToolDefinition(def model.ToolDefinition) (run.Digest, error) {
body, err := jsonstable.EncodeTypedPayload(preimageVersion, "tool_definition", def)
if err != nil {
return "", err
}
return jsonstable.DigestBytes(body), nil
}

type toolResponseDecisionDigestBody struct {
Kind run.ResponseKind `json:"kind"`
Decision run.ResponseDecision `json:"decision"`
Reason string `json:"reason,omitempty"`
}

type ToolResponsePayloadBody struct {
Payload run.CanonicalJSON `json:"payload"`
}

type ToolOutputBody struct {
Output run.CanonicalJSON `json:"output"`
}

func (Digests) DigestToolResponseDecision(kind run.ResponseKind, decision run.ResponseDecision, reason string) (run.Digest, error) {
if kind != run.ResponseApproval && kind != run.ResponseExternal {
return "", fmt.Errorf("agent: response decision: unsupported kind %q", kind)
}
if decision != run.ResponseDecisionApproved && decision != run.ResponseDecisionRejected {
return "", fmt.Errorf("agent: response decision: unsupported decision %q", decision)
}
body, err := jsonstable.EncodeTypedPayload(preimageVersion, "tool_response_decision", toolResponseDecisionDigestBody{
Kind: kind, Decision: decision, Reason: reason,
})
if err != nil {
return "", err
}
return jsonstable.DigestBytes(body), nil
}

func (Digests) DigestToolResponsePayload(payload run.CanonicalJSON) (run.Digest, error) {
body, err := jsonstable.EncodeTypedPayload(preimageVersion, ToolResponseType, ToolResponsePayloadBody{Payload: payload})
if err != nil {
return "", err
}
return jsonstable.DigestBytes(body), nil
}

// DigestModelResult names a frozen model result; ModelStepCompleted carries
// this digest and the frozen store holds the body (RUN-WIR-4).
func (Digests) DigestModelResult(result model.ModelResult) (run.Digest, error) { //nolint:gocritic // hugeParam: digest covers the complete immutable ModelResult value.
body, err := jsonstable.EncodeTypedPayload(preimageVersion, ModelResultType, result)
if err != nil {
return "", err
}
return jsonstable.DigestBytes(body), nil
}

// DigestToolOutput names one tool output; ToolCallCompleted carries it.
func (Digests) DigestToolOutput(output run.CanonicalJSON) (run.Digest, error) {
if output.IsZero() {
return "", errors.New("agent: tool output: empty output")
}
body, err := jsonstable.EncodeTypedPayload(preimageVersion, ToolOutputType, ToolOutputBody{Output: output})
if err != nil {
return "", err
}
return jsonstable.DigestBytes(body), nil
}
9 changes: 9 additions & 0 deletions agentcore/run/canonical/doc.go
< 8000 div class="file-actions pt-0 mb-md-0 mb-2 ml-md-2 flex-shrink-0 flex-md-justify-end">
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
// Package canonical is the canonical identity of a Run: the digest rules
// (Digests) for every body a fact names or a derived identity covers, and the
// derivation (Identity) of every RunID-scoped identity -- step, call,
// response, effect and command ids (RUN-WIR-1, RUN-WIR-4). Both are persisted
// semantics: their preimages never change (RUN-CMT-8). The state machine of
// agentcore/run is composed with them in agentcore/run/schema. The package
// also declares the envelope types under which agentcore/run/frozen stores
// the bodies these digests name.
package canonical
50 changes: 50 additions & 0 deletions agentcore/run/canonical/golden_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
package canonical

import (
"testing"

"github.com/felinics/twilight/agentcore/run"
)

// TestDerivedIdentityGolden freezes every derived identity of RUN-WIR-4 for
// one fixed input set. A drift with a non-empty want means the derivation
// preimage changed: intentional protocol changes must update this fixture and
// agent-run.md; anything else is accidental drift.
func TestDerivedIdentityGolden(t *testing.T) {
const (
runID run.RunID = "run-1"
step run.StepID = "step-1"
call run.CallID = "call-1"
effect run.EffectID = "effect-1"
)
cases := []struct {
name string
got string
want string
}{
{"model request command", string((Identity{}).DeriveModelRequestCommandID(runID, 7)), "7e42f75006e3271ce7420647345f238ee59e9603d596e7907cb2ccadc281763d"},
{"model step", string((Identity{}).DeriveModelStepID(runID, "cmd-1")), "883c5ef2aae151247361c311c41884dab6621d880aac6e3c285dcc2ad5ffa8e6"},
{"tool call", string((Identity{}).DeriveCallID(step, 0)), "cca7fd2e5a02a565155747fd8c126ac497a425d2f627eb2c77605dc0551aea11"},
{"tool step", string((Identity{}).DeriveToolStepID(step)), "6f62a482a83239b9c324a73c21b0b671ef2cad0af94a30177ed62929467d419d"},
{"response id", string((Identity{}).DeriveResponseID(runID, step, call, run.ResponseApproval)), "819924b49cc24df66e97f5821ac80bf286b983e600f20e25f045142c4bc0e77e"},
{"response command", string((Identity{}).DeriveResponseCommandID(runID, step, call, "resp-1")), "aacf7d247a13e4a696bff6f881ec517a6ad95ae262ec862d7dcf84b80c6bb32b"},
{"input command", string((Identity{}).DeriveInputCommandID(runID, "in-1")), "ce57abe29d2da34e02cf8fbfb7e4a25086b352096977094e9bed7eb66dd16aad"},
{"withdraw command", string((Identity{}).DeriveWithdrawCommandID(runID, step)), "582ffed8e0d762e83d68e0eef5c90f123e03787aad8462766667133d15961a8c"},
{"model effect", string((Identity{}).DeriveEffectID(runID, step, "", 1)), "553f030a642d4f74a09c2b11620e464f56f98711a97b522f82cc15771ccc3394"},
{"tool effect", string((Identity{}).DeriveEffectID(runID, step, call, 0)), "20fd10fde6bbb31634d80836d50906afc234e3676cfefb00a9abdb0fb996be78"},
{"start command", string((Identity{}).DeriveStartCommandID(effect)), "5fbd4523f88a2e24369724c7829e378883a83851f4164b78d0cd5d07c790fd3b"},
{"settlement command", string((Identity{}).DeriveSettlementCommandID(effect)), "6e05abc3045f404dfe76216a9bd84ec8b6ca0294177d60e9695ebd354446a01d"},
{"recovery command", string((Identity{}).DeriveRecoveryCommandID(effect)), "3059f690e0e819d6f1f08bdfe09f22c4012d1d284ee90c02c3e50175102d6735"},
{"decline command", string((Identity{}).DeriveDeclineCommandID(runID, step, call)), "c5eab65b0a9a2b828d18aed6ecc3655eff37cf55b275eb5fd15f26367637d49a"},
}
for _, c := range cases {
if c.got == c.want {
continue
}
if c.want == "" {
t.Errorf("UNSET %s = %s", c.name, c.got)
continue
}
t.Errorf("golden %s drifted — an intentional derivation change must update this fixture and agent-run.md:\n got: %s\nwant: %s", c.name, c.got, c.want)
}
}
132 changes: 132 additions & 0 deletions agentcore/run/canonical/identity.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
package canonical

import (
"crypto/sha256"
"encoding/hex"
"fmt"

"github.com/felinics/twilight/agentcore/run"
)

// namespacedHash derives a stable identifier from a namespace and ordered
// parts. Parts are length-prefixed so no two distinct part lists collide.
func namespacedHash(namespace string, parts ...string) string {
h := sha256.New()
fmt.Fprintf(h, "%d:%s", len(namespace), namespace)
for _, p := range parts {
fmt.Fprintf(h, "%d:%s", len(p), p)
}
return hex.EncodeToString(h.Sum(nil))
}

// Identity is the identity derivation: every RunID-scoped identity (steps,
// calls, responses, effects, command ids) is a namespaced hash of its
// preimage. The preimages are persisted semantics and never change: a
// different derivation would give a replayed command another CommitID
// (RUN-CMT-8).
type Identity struct{}

// DeriveModelRequestCommandID derives the CommandID for PrepareModelRequest
// from the Run and the RunPosition the prompt builder loaded (RUN-WIR-3): concurrent
// prompt builders on the same position converge on one command identity.
func (Identity) DeriveModelRequestCommandID(runID run.RunID, position run.RunPosition) run.CommandID {
return run.CommandID(namespacedHash("twilight/model-request", string(runID), fmt.Sprintf("%d", position)))
}

// DeriveModelStepID derives the ModelStep identity from the Run and the
// preparing command: one accepted Prepare opens one step.
func (Identity) DeriveModelStepID(runID run.RunID, cmd run.CommandID) run.StepID {
return run.StepID(namespacedHash("twilight/model-step", string(runID), string(cmd)))
}

// DeriveCallID derives the Run-owned identity of one tool call from the
// ModelStep that produced it and the call's position in that step's result.
// The provider's own tool_call_id is kept beside it as ProviderCallID for the
// request round trip; it is not trusted to be unique or non-empty.
func (Identity) DeriveCallID(source run.StepID, index int) run.CallID {
return run.CallID(namespacedHash("twilight/tool-call", string(source), fmt.Sprintf("%d", index)))
}

// DeriveToolStepID derives the ToolStep identity from its source ModelStep:
// a ModelStep completes once and opens at most one ToolStep.
func (Identity) DeriveToolStepID(source run.StepID) run.StepID {
return run.StepID(namespacedHash("twilight/tool-step", string(source)))
}

// DeriveResponseID derives the stable ResponseID the Machine assigns when it
// creates a Waiting request. One call has at most one outstanding request, so
// (run, step, call, kind) identifies it.
func (Identity) Deriv 8BD0 eResponseID(runID run.RunID, step run.StepID, call run.CallID, kind run.ResponseKind) run.ResponseID {
return run.ResponseID(namespacedHash("twilight/response", string(runID), string(step), string(call), string(kind)))
}

// DeriveResponseCommandID derives the CommandID for approval/rejection/answer
// commands: independent ingress processes converge on one command identity
// without coordination.
func (Identity) DeriveResponseCommandID(runID run.RunID, step run.StepID, call run.CallID, resp run.ResponseID) run.CommandID {
return run.CommandID(namespacedHash("twilight/response-command", string(runID), string(step), string(call), string(resp)))
}

// DeriveInputCommandID derives the CommandID for AcceptInput from the Run and
// the ordered InputIDs of the batch: the same inputs in the same order replay
// to the same command, a different batch is a different command. Queue-claim
// references stay private to the host.
func (Identity) DeriveInputCommandID(runID run.RunID, inputs ...run.InputID) run.CommandID {
parts := make([]string, 0, len(inputs)+1)
parts = append(parts, string(runID))
for _, in := range inputs {
parts = append(parts, string(in))
}
return run.CommandID(namespacedHash("twilight/input-command", parts...))
}

// DeriveWithdrawCommandID derives the CommandID of WithdrawPreparedStep: one
// Prepared step is withdrawn at most once, so the identity needs no content.
func (Identity) DeriveWithdrawCommandID(runID run.RunID, step run.StepID) run.CommandID {
return run.CommandID(namespacedHash("twilight/withdraw-command", string(runID), string(step)))
}

// DeriveEffectID derives the identity of one request for an external effect
// (RUN-WIR-1): the model call of a ModelStep (empty call) or one tool call of
// a ToolStep. sequence distinguishes the requests one step makes: a ModelStep
// whose result was rejected requests its model call again, so its sequence
// is the count of rejections before the request; a tool call starts at most
// once, so its sequence is 0. The EffectID is the one handle the Run and the
// execution plane share: the start, settlement and recovery commands of the
// effect derive from it, and the executor keys its attempts by it.
func (Identity) DeriveEffectID(runID run.RunID, step run.StepID, call run.CallID, sequence int) run.EffectID {
return run.EffectID(namespacedHash("twilight/effect", string(runID), string(step), string(call), fmt.Sprintf("%d", sequence)))
}

// DeriveStartCommandID derives the CommandID of StartModelExecution or
// StartToolCall from the effect it requests. Commit enforces this derivation
// so a caller-minted ID cannot bypass the idempotency index (RUN-WIR-3).
func (Identity) DeriveStartCommandID(effect run.EffectID) run.CommandID {
return run.CommandID(namespacedHash("twilight/start-command", string(effect)))
}

// DeriveSettlementCommandID derives the CommandID of the settlement of one
// effect (model result/failure/reject, tool result/failure). One effect
// settles once, so the identity needs no content: a replay with the same
// outcome is idempotent, a different outcome is a conflict.
func (Identity) DeriveSettlementCommandID(effect run.EffectID) run.CommandID {
return run.CommandID(namespacedHash("twilight/settlement-command", string(effect)))
}

// DeriveRecoveryCommandID derives the CommandID of the recovery of one effect
// whose outcome cannot be reached (RUN-CMT-7): RecoverModelExecution for a
// model effect, the Unknown SubmitToolFailure for a tool effect. The identity
// is a function of the effect alone, so whichever owner repeats the recovery
// replays the same command.
func (Identity) DeriveRecoveryCommandID(effect run.EffectID) run.CommandID {
return run.CommandID(namespacedHash("twilight/recovery-command", string(effect)))
}

// DeriveDeclineCommandID derives the CommandID of DeclineToolCall: the
// pre-start failure of one Pending call. The call has no effect yet and is
// declined at most once, so the identity is the call's coordinates alone; a
// replay of the same decline is idempotent, a different failure is a
// conflict.
func (Identity) DeriveDeclineCommandID(runID run.RunID, step run.StepID, call run.CallID) run.CommandID {
return run.CommandID(namespacedHash("twilight/decline-command", string(runID), string(step), string(call)))
}
7 changes: 7 additions & 0 deletions agentcore/run/frozen/doc.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
// Package frozen is the frozen-body protocol of a Run (RUN-WIR-4). Facts name
// the model request, model result, tool output and external tool response by
// digest only; Store is the port to the content-addressed side store that holds
// the bodies, and Codec stores each body as the typed envelope its digest was
// computed from, so sha256(bytes) == digest and the body is addressable by its
// own name.
package frozen
Loading
Loading
0