You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2026/09/24 16:33:52 UTC
(skywalking-ai-sessionizer) branch main updated: Show a headless run's question beside its answer (#40)
This is an automated email from the ASF dual-hosted git repository.
wu-sheng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/skywalking-ai-sessionizer.git
The following commit(s) were added to refs/heads/main by this push:
new 516287c Show a headless run's question beside its answer (#40)
516287c is described below
commit 516287c573e90412c9c33b19ce8aaaeea5a1a390
Author: 吴晟 Wu Sheng <wu...@foxmail.com>
AuthorDate: Fri Sep 25 00:33:46 2026 +0800
Show a headless run's question beside its answer (#40)
---
docs/en/adapters/claude-code-glossary.md | 4 +-
docs/en/adapters/claude-code.md | 13 +++--
docs/en/changes/changes.md | 8 +++
internal/adapters/claudecode/glossary.go | 4 +-
internal/adapters/claudecode/index.go | 22 +++++++-
internal/adapters/claudecode/prompt_source_test.go | 60 ++++++++++++++++++++++
internal/scenario/plan.go | 15 +++---
internal/scenario/scenario.go | 6 +++
internal/scenario/write_claudecode.go | 30 +++++++++--
tests/scenarios/sdk-prompt.expect.yaml | 23 +++++++++
tests/scenarios/sdk-prompt.yaml | 33 ++++++++++++
11 files changed, 198 insertions(+), 20 deletions(-)
diff --git a/docs/en/adapters/claude-code-glossary.md b/docs/en/adapters/claude-code-glossary.md
index fdceec5..1a2995d 100644
--- a/docs/en/adapters/claude-code-glossary.md
+++ b/docs/en/adapters/claude-code-glossary.md
@@ -48,12 +48,12 @@ together, because they sit in the same package, `internal/adapters/claudecode`.
| `epoch.boundary` | `system/compact_boundary` | a system record | |
| `epoch.summary` | `isCompactSummary` | a user record | |
| `error.api` | `system/api_error` | a system record | |
-| `external` | `origin.kind == "human"` | record | also a run whose records state no origin at all - a locally typed command |
+| `external` | `origin.kind == "human"` | record | also a user record with promptSource "sdk", no origin and no isMeta - a headless run's prompt - and a run whose records state no origin at all - a locally typed command |
| `follows` | `logicalParentUuid` | a compact_boundary record | |
| `id` | `uuid` | record | |
| `llm.call` | `message.id` | assistant records sharing one | one call is several records; 2.09 on average |
| `message.assistant` | `text block` | an assistant record | |
-| `message.external` | `origin.kind == "human"` | a user record | also a queued_command attachment whose commandMode is "prompt" |
+| `message.external` | `origin.kind == "human"` | a user record | also a user record with promptSource "sdk", no origin and no isMeta - a headless run's prompt - and a queued_command attachment whose commandMode is "prompt" |
| `message.synthetic` | `message.model == "<synthetic>"` | an assistant record | the client wrote it; no model produced it |
| `model` | `message.model` | an assistant record | `<synthetic>` on a record the client fabricated |
| `notification` | `origin.kind == "task-notification"` | record | |
diff --git a/docs/en/adapters/claude-code.md b/docs/en/adapters/claude-code.md
index 38cd1fb..e3e0f06 100644
--- a/docs/en/adapters/claude-code.md
+++ b/docs/en/adapters/claude-code.md
@@ -249,8 +249,8 @@ so `logicalParentUuid` is the only link back, and a parent walk across a reset s
### Talks and runs
-Claude Code records neither a Talk nor a Run. Both are built from two of its fields, `promptId` and
-`origin`, by an exact rule.
+Claude Code records neither a Talk nor a Run. Both are built from its fields `promptId` and
+`origin`, and `promptSource` for a headless run's prompt, by an exact rule.
- **A run is one prompt cycle**: one per distinct `promptId` within a stream. A `promptId` is not
unique across streams, because a child stream is written under a cycle id that also appears in its
@@ -265,6 +265,13 @@ Claude Code records neither a Talk nor a Run. Both are built from two of its fie
`task-notification` is a notification. The value is an open set: a third kind exists, so any
other value maps to `unknown`, and a switch on exactly two values would meet something it does
not expect.
+- **A headless run's prompt has no `origin`.** `claude -p` and an Agent SDK application write
+ `promptSource: "sdk"` on the prompt instead, and a `user` record with it, no `origin` and no
+ `isMeta` is external. On this machine on 2026-09-24, 36 non-meta `user` records carried
+ `promptSource: "sdk"` and no `origin`: 35 were a caller's prompt and one a person's message on a
+ resumed session. One more was meta, a notice the harness wrote. No tool result carried it. A
+ prompt that states an `origin` is read by it, so a notification sent through the SDK stays a
+ notification.
- **On the main stream, a Talk starts when a cycle has an external trigger, or when no record of
the cycle states any trigger.** A local slash command writes no `origin`, and it is a person
acting, so a rule that required an explicit marker would attach it to whatever came before. A
@@ -285,7 +292,7 @@ pass.
| Model kind | Claude Code source | Quality |
| --- | --- | --- |
-| `message.external` | `user` record with `origin.kind:"human"` and without `isMeta`; a `queued_command` attachment with `commandMode:"prompt"` | `exact_unique` |
+| `message.external` | `user` record with `origin.kind:"human"` and without `isMeta`; a `user` record with `promptSource:"sdk"`, no `origin` and without `isMeta`; a `queued_command` attachment with `commandMode:"prompt"` | `exact_unique` |
| `message.assistant` | assistant `text` block | `exact_unique` |
| `message.synthetic` | `message.model == "<synthetic>"` | `exact_unique` |
| `context.injection` | every other `attachment` record; a `user` record with `isMeta:true` | `exact_unique` |
diff --git a/docs/en/changes/changes.md b/docs/en/changes/changes.md
index a536f6c..e934fd8 100644
--- a/docs/en/changes/changes.md
+++ b/docs/en/changes/changes.md
@@ -23,6 +23,14 @@
before it. The renderer is Horizon's, now pinned at `297f020`, which also draws a light theme's
scrollbars and other native controls light.
+## Claude Code
+
+- A headless run's question is on the page. `claude -p` and an Agent SDK application write their
+ prompt with `promptSource: "sdk"` and no `origin`, and only `origin.kind: "human"` was read as a
+ person's input, so the page showed each answer without the question it answered. Such a prompt
+ is now external input that opens its talk. A session collected before this keeps the gap, because
+ landed records are never rewritten.
+
## Development
- The first benchmark: `BenchmarkLangChainRequests` measures cutting every request body of one
diff --git a/internal/adapters/claudecode/glossary.go b/internal/adapters/claudecode/glossary.go
index dfb6f8f..ad4cc0a 100644
--- a/internal/adapters/claudecode/glossary.go
+++ b/internal/adapters/claudecode/glossary.go
@@ -73,7 +73,7 @@ var glossary = model.NewGlossary(Dialect,
// ---- steps ----
model.Term{Unified: model.KindMessageExternal, Native: "origin.kind == \"human\"", Where: "a user record",
- Note: "also a queued_command attachment whose commandMode is \"prompt\""},
+ Note: "also a user record with promptSource \"sdk\", no origin and no isMeta - a headless run's prompt - and a queued_command attachment whose commandMode is \"prompt\""},
model.Term{Unified: model.KindMessageAssistant, Native: "text block", Where: "an assistant record"},
model.Term{Unified: model.KindMessageSynthetic, Native: "message.model == \"<synthetic>\"", Where: "an assistant record",
Note: "the client wrote it; no model produced it"},
@@ -134,7 +134,7 @@ var glossary = model.NewGlossary(Dialect,
model.Term{Unified: model.ContentUnavailable, Note: "the runtime never wrote it, or the source was pruned"},
model.Term{Unified: model.TriggerExternal, Native: "origin.kind == \"human\"", Where: "record",
- Note: "also a run whose records state no origin at all - a locally typed command"},
+ Note: "also a user record with promptSource \"sdk\", no origin and no isMeta - a headless run's prompt - and a run whose records state no origin at all - a locally typed command"},
model.Term{Unified: model.TriggerNotification, Native: "origin.kind == \"task-notification\"", Where: "record"},
model.Term{Unified: model.TriggerUnknown, Note: "no record of the run states a trigger"},
)
diff --git a/internal/adapters/claudecode/index.go b/internal/adapters/claudecode/index.go
index a9c90ff..34fbdc8 100644
--- a/internal/adapters/claudecode/index.go
+++ b/internal/adapters/claudecode/index.go
@@ -66,6 +66,9 @@ type indexRecord struct {
ParentAgentID string `json:"parentAgentId"`
Origin origin `json:"origin"`
+ // PromptSource says how a prompt reached the runtime. A headless run's
+ // prompt has no origin, and this is what says a caller sent it.
+ PromptSource string `json:"promptSource"`
Message struct {
ID string `json:"id"`
@@ -172,6 +175,9 @@ func triggerOf(d *indexRecord) index.Trigger {
if kind == "" {
kind = d.Attachment.Origin.Kind
}
+ if kind == "" && sdkPrompt(d) {
+ return index.TriggerExternal
+ }
switch kind {
case "":
return index.TriggerNone
@@ -183,6 +189,20 @@ func triggerOf(d *indexRecord) index.Trigger {
return index.TriggerOther
}
+// sdkPrompt reports the prompt a caller sent a headless run: claude -p, or an
+// Agent SDK application.
+//
+// Such a prompt has no origin. The runtime writes promptSource "sdk" on it
+// instead. Measured on the local corpus, 36 non-meta user records carry it
+// with no origin, 35 of them a caller's prompt and one a person's message on
+// a resumed session, and no tool result carries it. One more carries it and
+// is meta, a notice the harness wrote, which is why meta is excluded. A
+// prompt that does say where it came from is read by its origin, so a
+// notification sent through the SDK stays a notification.
+func sdkPrompt(d *indexRecord) bool {
+ return d.Type == "user" && d.Origin.Kind == "" && d.PromptSource == "sdk" && !d.IsMeta
+}
+
// flagsOf reduces the record's shape to the bits a lookup needs.
func flagsOf(d *indexRecord, tur *toolResult, hasTUR bool, src Source) index.Flags {
var f index.Flags
@@ -262,7 +282,7 @@ func flagsOf(d *indexRecord, tur *toolResult, hasTUR bool, src Source) index.Fla
f |= index.FlagInjection
}
}
- if d.Type == "user" && d.Origin.Kind == "human" && !d.IsMeta {
+ if d.Type == "user" && (d.Origin.Kind == "human" || sdkPrompt(d)) && !d.IsMeta {
f |= index.FlagExternalInput
}
if d.IsMeta {
diff --git a/internal/adapters/claudecode/prompt_source_test.go b/internal/adapters/claudecode/prompt_source_test.go
new file mode 100644
index 0000000..d609ea4
--- /dev/null
+++ b/internal/adapters/claudecode/prompt_source_test.go
@@ -0,0 +1,60 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package claudecode
+
+import (
+ "encoding/json"
+ "testing"
+
+ "github.com/apache/skywalking-ai-sessionizer/internal/index"
+)
+
+// TestAPromptSentThroughTheSDK reads the record shapes measured on the local
+// corpus. Only a prompt with no origin and no isMeta is a caller's: the SDK
+// also writes promptSource on notifications, which keep their origin, and on
+// a harness notice, which is meta and is not something anyone asked.
+func TestAPromptSentThroughTheSDK(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ line string
+ external bool
+ trigger index.Trigger
+ }{
+ {"headless prompt", `{"type":"user","promptSource":"sdk","message":{"role":"user","content":"read the README"}}`,
+ true, index.TriggerExternal},
+ {"notification through the SDK", `{"type":"user","promptSource":"sdk","origin":{"kind":"task-notification"},"message":{"role":"user","content":"<task-notification>"}}`,
+ false, index.TriggerNotification},
+ {"harness notice through the SDK", `{"type":"user","promptSource":"sdk","isMeta":true,"message":{"role":"user","content":"[Cross-session idle notice]"}}`,
+ false, index.TriggerNone},
+ {"prompt a person typed in VS Code", `{"type":"user","promptSource":"sdk","origin":{"kind":"human"},"message":{"role":"user","content":"hello"}}`,
+ true, index.TriggerExternal},
+ {"no promptSource and no origin", `{"type":"user","message":{"role":"user","content":"Continue from where you left off."}}`,
+ false, index.TriggerNone},
+ } {
+ var d indexRecord
+ if err := json.Unmarshal([]byte(tc.line), &d); err != nil {
+ t.Fatal(err)
+ }
+ if got := flagsOf(&d, nil, false, Source{}).Has(index.FlagExternalInput); got != tc.external {
+ t.Errorf("%s: external input %v, want %v", tc.name, got, tc.external)
+ }
+ if got := triggerOf(&d); got != tc.trigger {
+ t.Errorf("%s: trigger %v, want %v", tc.name, got, tc.trigger)
+ }
+ }
+}
diff --git a/internal/scenario/plan.go b/internal/scenario/plan.go
index ebbba62..b0a8132 100644
--- a/internal/scenario/plan.go
+++ b/internal/scenario/plan.go
@@ -215,12 +215,13 @@ type JournalLine struct {
// Plan is a scenario resolved into timed records with stable ids.
type Plan struct {
- Session string
- Project string
- Title string
- Events []Event
- Streams []Stream
- Runs []Run
+ Session string
+ Project string
+ Title string
+ Entrypoint string
+ Events []Event
+ Streams []Stream
+ Runs []Run
// SystemPrompt and Tools are what the main stream's calls send, as the
// scenario wrote them. Empty leaves the stand-in. See ProviderBodies.
//
@@ -294,7 +295,7 @@ func (sc *Scenario) Plan(opts Options) (*Plan, error) {
if scale == 0 {
scale = 1
}
- p := &Plan{Session: sc.Session, Project: sc.Project, Title: sc.Title, Provider: sc.ProviderBodies, bodies: sc.ProviderBodies && !sc.omitBodies, at: at, interval: interval, scale: scale,
+ p := &Plan{Session: sc.Session, Project: sc.Project, Title: sc.Title, Entrypoint: sc.Entrypoint, Provider: sc.ProviderBodies, bodies: sc.ProviderBodies && !sc.omitBodies, at: at, interval: interval, scale: scale,
SystemPrompt: sc.SystemPrompt, Tools: sc.Tools}
if p.Project == "" {
p.Project = "-Users-dev-scenario"
diff --git a/internal/scenario/scenario.go b/internal/scenario/scenario.go
index f4acb0f..b518bc9 100644
--- a/internal/scenario/scenario.go
+++ b/internal/scenario/scenario.go
@@ -51,6 +51,12 @@ type Scenario struct {
// Title is the name the runtime gave the session, written as the
// runtime writes it. Empty means the session has no title.
Title string `yaml:"title"`
+ // Entrypoint is how the runtime was started, as it records it. Empty is
+ // the interactive command line. "sdk-cli" is a headless run, claude -p or
+ // an Agent SDK application: every input of the main stream is then the
+ // caller's prompt, which carries promptSource "sdk" and no origin, and is
+ // sent as a plain string.
+ Entrypoint string `yaml:"entrypoint"`
// Interval is the session's clock: the gap between consecutive steps in
// every stream, unless a step says after. Zero means one second.
Interval time.Duration `yaml:"interval"`
diff --git a/internal/scenario/write_claudecode.go b/internal/scenario/write_claudecode.go
index 911a34d..db3a4be 100644
--- a/internal/scenario/write_claudecode.go
+++ b/internal/scenario/write_claudecode.go
@@ -207,10 +207,17 @@ func ccTime(t time.Time) string { return t.UTC().Format("2006-01-02T15:04:05.000
const ccModel = "claude-opus-5"
// rec adds the envelope every Claude Code record carries.
+func (w *ccWriter) entrypoint() string {
+ if w.p.Entrypoint != "" {
+ return w.p.Entrypoint
+ }
+ return "cli"
+}
+
func (w *ccWriter) rec(m map[string]any, stream string) string {
for k, v := range map[string]any{
"sessionId": w.p.Session, "version": "2.1.245", "userType": "external",
- "entrypoint": "cli", "cwd": "/Users/dev/" + strings.TrimPrefix(w.p.Project, "-Users-dev-"), "gitBranch": "main",
+ "entrypoint": w.entrypoint(), "cwd": "/Users/dev/" + strings.TrimPrefix(w.p.Project, "-Users-dev-"), "gitBranch": "main",
} {
if _, ok := m[k]; !ok {
m[k] = v
@@ -255,11 +262,18 @@ func (w *ccWriter) event(e *Event) error {
"type": "user", "uuid": e.ID, "parentUuid": parentOf(e.Parent), "promptId": e.Run,
"timestamp": ccTime(e.At),
}
- if s == "main" {
+ switch {
+ case s == "main" && w.p.Entrypoint == "sdk-cli":
+ // The caller's prompt, as a headless run writes it: no origin,
+ // and promptSource says it came through the SDK.
+ m["promptSource"] = "sdk"
+ m["permissionMode"] = "bypassPermissions"
+ m["message"] = map[string]any{"role": "user", "content": e.Text}
+ case s == "main":
m["origin"] = map[string]any{"kind": "human"}
m["permissionMode"] = "auto"
m["message"] = map[string]any{"role": "user", "content": []map[string]any{{"type": "text", "text": e.Text}}}
- } else {
+ default:
m["message"] = map[string]any{"role": "user", "content": e.Text}
}
w.add(s, w.rec(m, s))
@@ -333,11 +347,17 @@ func (w *ccWriter) event(e *Event) error {
}
w.add(s, w.rec(m, s))
case EvNotice:
- w.add(s, w.rec(map[string]any{
+ m := map[string]any{
"type": "user", "uuid": e.ID, "parentUuid": parentOf(e.Parent), "promptId": e.Run,
"origin": map[string]any{"kind": "task-notification"}, "timestamp": ccTime(e.At),
"message": map[string]any{"role": "user", "content": e.Text},
- }, s))
+ }
+ if w.p.Entrypoint == "sdk-cli" {
+ // A headless run marks its notifications as sent through the SDK
+ // too, and they keep their origin.
+ m["promptSource"] = "sdk"
+ }
+ w.add(s, w.rec(m, s))
case EvSynthetic:
w.add(s, w.rec(map[string]any{
"type": "assistant", "uuid": e.ID, "parentUuid": parentOf(e.Parent), "requestId": e.Req, "timestamp": ccTime(e.At),
diff --git a/tests/scenarios/sdk-prompt.expect.yaml b/tests/scenarios/sdk-prompt.expect.yaml
new file mode 100644
index 0000000..06597db
--- /dev/null
+++ b/tests/scenarios/sdk-prompt.expect.yaml
@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+checkpoints:
+ final:
+ kinds: {message.external: 2, runtime.notification: 1, tool: 1}
+ talks_on: {main: 2, scout: 1}
+ relations: {starts: 1, reports: 1}
+ view: {state: verified, talks: 3}
diff --git a/tests/scenarios/sdk-prompt.yaml b/tests/scenarios/sdk-prompt.yaml
new file mode 100644
index 0000000..d663e89
--- /dev/null
+++ b/tests/scenarios/sdk-prompt.yaml
@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# A headless run, claude -p or an Agent SDK application, over two prompts. Its
+# prompts carry no origin: the runtime writes promptSource "sdk" instead, on
+# every one measured. Each prompt is still the input that opens its talk, and
+# the question has to be on the page beside its answer. The run also marks a
+# background agent's notification as sent through the SDK, and that one keeps
+# its origin: it reports the agent, and is not a question.
+title: headless run
+entrypoint: sdk-cli
+steps:
+ - input: read the README and say what the project is
+ - call: {text: Reading it, tool: {name: Read, input: {file_path: README.md}, result: "# asz"}}
+ - call: {text: It is asz.}
+ - input: and what does it collect
+ - call:
+ agent: {name: scout, prompt: list what it collects, steps: [{call: {text: transcripts}}], notify: true}
+ - call: {text: Conversation logs.}