Skip to content

feat(examples): the owner approves crew repair tickets, and a guide to the nine use cases - #2078

Open
isekovanic wants to merge 1 commit into
chore/rn-samples-catch-upfrom
feat/crew-ticket-approval
Open

isekovanic wants to merge 1 commit into
chore/rn-samples-catch-upfrom
feat/crew-ticket-approval

Conversation

@isekovanic

Copy link
Copy Markdown
Contributor

Linear: AI-2605 (approvals from other users), AI-2610 (integration guide for the nine use cases)

Stacked on #2058, which is stacked on #2007.

Why

Two of the restaurant use cases weren't covered by the crew sample yet:

  • a repair ticket the team member drafts has to be approved by the owner, in the owner's own app, before it's submitted, and the team member has to hear the outcome, possibly hours later;
  • there was no single guide mapping each use case to what Stream provides and what the customer's backend adds.

Changes

The owner approves tickets (AI-2605)

  • create_support_ticket now drafts a ticket that waits for the owner (waiting_for in the leaders' inbox), with the conversation it came from and the phone's timezone. The call ends there, so nothing holds the session while the owner decides.
  • POST /crew/tickets/{id}/decision with {"approve": true | false}, plus the owner's edits to title or details if any. It answers only the user the ticket waits for. Approving submits it to repairs.
  • Either way, the backend has the agent tell the team member in that conversation, through the same scheduled task as speaking first (agentSpeaksFirst now takes a title and instructions rather than an event kind).
  • The team lead view signs in as the owner by default (crew-taylor) and shows Approve and submit and Reject on tickets waiting for them.
  • instructions.md and the approval card tell the person that the owner approves it and that they'll hear back.

Timezone on iOS

  • A scheduled task needs the person's timezone, and on an iOS simulator Hermes can't name it (Intl.DateTimeFormat().resolvedOptions().timeZone is empty), so the router refused the task. phoneTimezone() falls back to the phone's UTC offset as an Etc/GMT±N zone. Clock-in and the other events use it too, since they had the same problem there.

The guide (AI-2610)

  • USE_CASES.md: for each of the nine use cases, what the team member does, what Stream gives, what your backend builds, and where the sample shows it. Linked from the README.

Validation

  • go test ./... in backend/, with a new test: the owner approves with an edit, the drafter and a shift leader can't, the drafter is told in their conversation and timezone, and a decided ticket can't be decided again.
  • npm run typecheck and npm test (12 tests) in app/, including the ticket's session and timezone and the timezone fallback.
  • On device, against a local router built from main: Jordan drafted a fryer ticket on the iOS simulator; Taylor approved it in the team lead view on the Android emulator; Jordan's open conversation on iOS then showed "Taylor Morgan approved your fryer ticket and sent it to repairs as REP-304". Reject was checked over HTTP and in the test, not on device.

…o the nine use cases

A repair ticket the team member drafts now waits for the owner. The team lead view, signed in as
the owner by default, approves it, which submits it to repairs, or rejects it. Either way the
backend has the agent tell the team member in the conversation the ticket came from, through a
scheduled task as speaking first does, so a decision hours later still reaches them. The call
that drafted the ticket ends at once, and nothing waits on the owner.

The phone sends its timezone with the ticket, which a scheduled task needs. Hermes on an iOS
simulator can't name the zone, so the phone's UTC offset stands in as an Etc/GMT zone, for
clock-in and the other events too.

USE_CASES.md walks through the nine use cases: what Stream gives, what your backend adds, and
where the sample shows each.

Linear: AI-2605, AI-2610
@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Walkthrough

The crew assistant adds an owner approval flow for repair-ticket drafts. The app sends the conversation session and timezone with ticket requests, and the leader view provides approval and rejection controls. The backend applies the owner’s decision, supports title and details edits, and can schedule an outcome message to the drafter. The changes also update the sample configuration and documentation, add use-case documentation, and test the ticket decision and timezone behavior.

Merge Risk: Moderate · up to 1d1a7

Owner approval for repair tickets works, but a request that omits approve is treated as a rejection. A failed or cancelled notification can also leave the team member without the promised outcome, because retrying the decision returns 409. Fix these two before merging; the remaining items are minor.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

golangci-lint (2.15.0)

level=error msg="[linters_context] typechecking error: current directory is contained in a module that is not one of the workspace modules listed in go.work. You can add the module to the workspace using:\n\tgo work use ."

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Finishing Touches
Fix failing CI checks

  • Commit to this branch
  • Create a new PR

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 13

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (2)

Minor · Discard inbox responses from superseded reads. · leader.tsx:54

examples/voice_agents/crew_assistant/app/app/leader.tsx:54
Minor · Stability & Availability · Quick win

Discard inbox responses from superseded reads.

If a poll reads a pending ticket before approval but returns after the post-decision reload, setInbox restores the old row and its decision buttons. An owner who presses one gets a 409. Apply an inbox response only if no newer read has started.

Minor · Distinguish owner decisions from in-chat tool approvals. · README.md:116

examples/voice_agents/crew_assistant/app/README.md:116
Minor · Functional Correctness · Quick win

Distinguish owner decisions from in-chat tool approvals.

Line 116 says a user other than the person chatting cannot answer an approval. The new ticket workflow lets the owner do exactly that from Team lead. If the limitation applies only to in-chat tool approval cards, say so explicitly.

Minor comments: 1

examples/voice_agents/crew_assistant/backend/main.go: 1

177-180: Minor · Functional Correctness · Poor tradeoff

Keep the task when the manual run fails.

The two-minute cleanup deletes the task whether or not the run succeeded. If the run fails, the deletion also removes the task's one-day occurrence, which is the only remaining attempt to deliver the decision notice to the drafter. Delete the task only after a successful run. If the run fails, keep the task so its occurrence can deliver the outcome.

This does not cancel a delivery already in progress. The risk is limited to the failure path.

Review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between e459dcf and 1d1a77b.

Files selected for processing: 15

  • examples/voice_agents/crew_assistant/README.md
  • examples/voice_agents/crew_assistant/USE_CASES.md
  • examples/voice_agents/crew_assistant/app/.env.example
  • examples/voice_agents/crew_assistant/app/README.md
  • examples/voice_agents/crew_assistant/app/agent/config.ts
  • examples/voice_agents/crew_assistant/app/agent/crewTools.ts
  • examples/voice_agents/crew_assistant/app/app/leader.tsx
  • examples/voice_agents/crew_assistant/app/contexts/AppContext.tsx
  • examples/voice_agents/crew_assistant/app/tests/deviceTools.test.ts
  • examples/voice_agents/crew_assistant/backend/backend_test.go
  • examples/voice_agents/crew_assistant/backend/crew.go
  • examples/voice_agents/crew_assistant/backend/hosted.go
  • examples/voice_agents/crew_assistant/backend/http.go
  • examples/voice_agents/crew_assistant/backend/main.go
  • examples/voice_agents/crew_assistant/instructions.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 6 remain after this review.

Comment on lines +39 to +40
name: 'Taylor Morgan',
title: 'owner',

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Functional Correctness · Quick win

Use owner labels only for the owner account.

With EXPO_PUBLIC_AGENT_LEADER_ID=crew-maya, the view still signs in as Maya, but now says “Signed in as Taylor Morgan, owner.” The backend correctly withholds Taylor's approval controls, which makes that label misleading. Keep the owner labels for crew-taylor. For overrides, display the selected user's identity or a neutral label. (raw.githubusercontent.com)

const named = Intl.DateTimeFormat().resolvedOptions().timeZone;
if (named) return named;
const hours = new Date().getTimezoneOffset() / 60;
return Number.isInteger(hours) ? `Etc/GMT${hours < 0 ? '' : '+'}${hours}` : undefined;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Data Integrity & Integration · Quick win

Provide a scheduling timezone for fractional offsets.

If Hermes returns no zone name on a UTC+05:30 phone, this helper omits timezone. For a fresh user with no stored timezone and an agent with no default, the router refuses to create the decision notice. Use a native timezone source that supports fractional-offset regions. If no reliable zone is available, use an explicit scheduling default rather than silently omitting the field. Keep named zones and valid whole-hour fallbacks unchanged. (raw.githubusercontent.com)

const [pulse, setPulse] = useState<Pulse>();
const [failure, setFailure] = useState<string>();
const [refreshing, setRefreshing] = useState(false);
const [deciding, setDeciding] = useState<string>();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Stability & Availability · Quick win

Track pending decisions per ticket.

If the owner starts a decision on ticket B while ticket A is pending, setDeciding(B) re-enables A's controls. The owner can send a second POST for A and get a 409 after the first decision succeeds. Track pending IDs per ticket, and remove only the ID whose request finishes.

expect(crewBackend).toHaveBeenCalledWith('crew/tickets', { body: args });
// The conversation and timezone it came from, where the person hears what the owner decided.
expect(crewBackend).toHaveBeenCalledWith('crew/tickets', {
body: { ...args, session_id: 'session-1', timezone: phoneTimezone() },

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Functional Correctness · Quick win

Assert a fixed timezone in the ticket payload.

The ticket handler and this assertion both call phoneTimezone(). If it always returns Etc/GMT-1, both tests can pass even when a UTC+02:00 phone sends the wrong zone. Stub an unnamed UTC+02:00 phone in the ticket test and expect the literal Etc/GMT-2. Restore the spies and the session fixture after the test.

As per path instructions, flag “tests that would still pass on a broken implementation.”

Source: Path instructions

Comment on lines +350 to +352
if got := request(t, handler, "POST", decision, taylor, map[string]any{"approve": false}); got.Code != http.StatusConflict {
t.Errorf("a decided ticket was decided again: %d", got.Code)
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Trivial · Maintainability & Code Quality · Quick win

Check that a rejected replay does not send a second notice.

The test checks heard before replaying the decision. A regression that sends another notice and then returns 409 would still pass. Assert that heard still contains exactly one entry after the replay. As per path instructions, flag “tests that would still pass on a broken implementation.”

Source: Path instructions

Comment on lines +188 to +189
instructions := fmt.Sprintf("Tell the person what happened to the repair ticket they drafted, %q: %s. "+
"Say it in one or two short sentences, and call no tools.", item.Title, item.Status)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Data Integrity & Integration · Quick win

Keep ticket notices within the scheduler's instructions limit.

A 2,100-character ticket title is valid here, but embedding it in full exceeds the router's 2,000-character instructions limit. The owner sees a final decision, and the drafter gets no notice. Use the ticket ID and a bounded title excerpt. Apply the limit to the final formatted instructions because quoting can expand the title. (raw.githubusercontent.com)

Comment on lines +190 to +192
if _, err := s.speak(r.Context(), item.drafter, item.session, "Your repair ticket", instructions, item.timezone); err != nil {
log.Printf("couldn't tell %s about %s: %v", item.drafter, item.ID, err)
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Stability & Availability · Heavy lift

Keep the notification retryable after the decision commits.

If the owner disconnects after crew.decide commits but before task creation, the canceled request can prevent scheduling. A transient create failure leaves the same state. The ticket stays decided, and another POST returns 409 before it can retry the notice.

Record pending notification work with the decision. Submit it with an independent, bounded context and a stable task identity so a retry does not reapply the decision or create duplicate tasks. Keep the recorded decision visible to the owner. If you log a retry failure, put the ticket ID and error in structured fields. Based on learnings, choose context according to the lifetime of the work. As per coding guidelines, “Log with log/slog. Put the data in key-value fields, not in the message.”

Sources: Coding guidelines, Learnings

time.Sleep(2 * time.Minute)
if deleted, err := client.DeleteScheduledTaskWithResponse(context.Background(), id); err != nil || deleted.StatusCode() >= http.StatusMultipleChoices {
log.Printf("the %s task %s stays scheduled: %v", kind, id, err)
log.Printf("the %q task %s stays scheduled: %v", title, id, err)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Maintainability & Code Quality · Quick win

Log the HTTP status and task details with slog in the cleanup warning.

When the delete call returns a non-2xx status without a transport error, err is nil. The current warning then prints <nil> and omits the status, so the reason the task stays scheduled is lost. The message also places the title and ID in the text instead of in key-value fields. The Go guidelines for this repository require log/slog with key-value fields.

Split the error and status checks so that deleted is read only when err is nil, and log each case with its own fields. Add log/slog to the imports.

Suggested fix

--- "a/examples/voice_agents/crew_assistant/backend/main.go"
+++ "b/examples/voice_agents/crew_assistant/backend/main.go"
@@ -177,9 +177,12 @@
 	// The task was only a way to run once now: it goes once its run is well under way.
 	go func(id string) {
 		time.Sleep(2 * time.Minute)
-		if deleted, err := client.DeleteScheduledTaskWithResponse(context.Background(), id); err != nil || deleted.StatusCode() >= http.StatusMultipleChoices {
-			log.Printf("the %q task %s stays scheduled: %v", title, id, err)
-		}
+		deleted, err := client.DeleteScheduledTaskWithResponse(context.Background(), id)
+		if err != nil {
+			slog.Warn("scheduled task stays scheduled", "task", id, "title", title, "error", err)
+		} else if deleted.StatusCode() >= http.StatusMultipleChoices {
+			slog.Warn("scheduled task stays scheduled", "task", id, "title", title, "status", deleted.StatusCode())
+		}
 	}(task.Id)
 	return task.Id, nil
 }

safety first. If it doesn't work, or there's no guide, offer a repair ticket and draft it with
create_support_ticket from what they saw and tried.
create_support_ticket from what they saw and tried. The owner approves it before it goes to
repairs: say so, and that they'll hear back here once it's decided.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Data Integrity & Integration · Heavy lift

Do not promise a follow-up that can be lost.

If scheduled-task creation or execution fails, the decision handler logs the error and returns success. The decision is already final, so a retry receives 409 and the drafter never hears the outcome. Hosted ticket calls also supply no session, so the handler skips notification. Ensure those paths can deliver the outcome before the agent promises it here.

Comment on lines +50 to +52
- **Health details:** the note to the leader takes a reason from a fixed list (`sick`, `family`,
`transport`, `other`), so nothing the person said about their health reaches it. The person's own
conversation still holds what they wrote.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Security & Privacy · Quick win

Clarify that the leader learns the person is sick.

The fixed reason sick tells the leader that the person reported an illness. It does not disclose their symptoms, but it contradicts the claim that nothing about their health reaches the note. Limit the claim to symptoms and other health details.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant