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
5 changes: 5 additions & 0 deletions .changeset/assume-session-creator-create-turn.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@truefoundry/trueforge': patch
---

Service API key may create or list turns on `/api/v1/sessions/{session_id}/turns` with `assume-user: session-creator` (identity is the session creator).
24 changes: 24 additions & 0 deletions .github/fern/openapi/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -10724,6 +10724,18 @@
"get": {
"description": "List turns for a session (newest first by default), token-paginated. Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.",
"parameters": [
{
"description": "Service API key only: which user identity to assume. Currently only session-creator.",
"in": "header",
"name": "assume-user",
"required": false,
"schema": {
"enum": [
"session-creator"
],
Comment thread
thesujai marked this conversation as resolved.
Resolved
"type": "string"
}
},
{
"description": "Session identifier.",
"in": "path",
Expand Down Expand Up @@ -10819,6 +10831,18 @@
"post": {
"description": "Create a turn within a session and execute it.\nOnly the session creator may create turns.\nWhen `stream` is true (default), respond with a Server-Sent Events stream of turn events.\nWhen `stream` is false, return the turn immediately with `state.status: \"running\"` while execution continues in the background; use get turn or subscribe to observe completion.\nUse `previous_turn_id` to chain to the session's last turn (defaults to `auto`); use `none` for a new root.",
"parameters": [
{
"description": "Service API key only: which user identity to assume. Currently only session-creator.",
"in": "header",
"name": "assume-user",
"required": false,
"schema": {
"enum": [
"session-creator"
],
"type": "string"
}
},
{
"description": "Session identifier.",
"in": "path",
Expand Down
24 changes: 24 additions & 0 deletions docs/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -10724,6 +10724,18 @@
"get": {
"description": "List turns for a session (newest first by default), token-paginated. Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.",
"parameters": [
{
"description": "Service API key only: which user identity to assume. Currently only session-creator.",
"in": "header",
"name": "assume-user",
"required": false,
"schema": {
"enum": [
"session-creator"
],
"type": "string"
}
},
{
"description": "Session identifier.",
"in": "path",
Expand Down Expand Up @@ -10819,6 +10831,18 @@
"post": {
"description": "Create a turn within a session and execute it.\nOnly the session creator may create turns.\nWhen `stream` is true (default), respond with a Server-Sent Events stream of turn events.\nWhen `stream` is false, return the turn immediately with `state.status: \"running\"` while execution continues in the background; use get turn or subscribe to observe completion.\nUse `previous_turn_id` to chain to the session's last turn (defaults to `auto`); use `none` for a new root.",
"parameters": [
{
"description": "Service API key only: which user identity to assume. Currently only session-creator.",
"in": "header",
"name": "assume-user",
"required": false,
"schema": {
"enum": [
"session-creator"
],
"type": "string"
}
},
{
"description": "Session identifier.",
"in": "path",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

import type { BaseClientOptions, BaseRequestOptions } from "../../../../BaseClient.js";
import { type NormalizedClientOptionsWithAuth, normalizeClientOptionsWithAuth } from "../../../../BaseClient.js";
import { mergeHeaders } from "../../../../core/headers.js";
import { mergeHeaders, mergeOnlyDefinedHeaders } from "../../../../core/headers.js";
import * as core from "../../../../core/index.js";
import { mergeAdditionalBodyParameters } from "../../../../core/requestBody.js";
import { handleNonStatusCodeError } from "../../../../errors/handleNonStatusCodeError.js";
Expand Down Expand Up @@ -1112,7 +1112,7 @@ export class SessionsClient {
async (
request: TrueForge.ListTurnsSessionsRequest,
): Promise<core.WithRawResponse<TrueForge.ListTurnsResponse>> => {
const { limit = 25, pageToken } = request;
const { limit = 25, pageToken, assumeUser } = request;
const _queryParams: Record<string, unknown> = {
limit,
page_token: pageToken,
Expand All @@ -1121,6 +1121,7 @@ export class SessionsClient {
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
this._options?.headers,
mergeOnlyDefinedHeaders({ "assume-user": assumeUser }),
requestOptions?.headers,
);
const _response = await (this._options.fetcher ?? core.fetcher)({
Expand Down Expand Up @@ -1239,10 +1240,12 @@ export class SessionsClient {
request: TrueForge.CreateTurnSessionsStreamRequest,
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<core.Stream<TrueForge.TurnStreamingEvent>>> {
const { assumeUser, ..._body } = request;
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
this._options?.headers,
mergeOnlyDefinedHeaders({ "assume-user": assumeUser }),
requestOptions?.headers,
);
const _response = await (this._options.fetcher ?? core.fetcher)<ReadableStream>({
Expand All @@ -1258,7 +1261,7 @@ export class SessionsClient {
requestType: "json",
body: mergeAdditionalBodyParameters(
{
...serializers.CreateTurnSessionsStreamRequest.jsonOrThrow(request, {
...serializers.CreateTurnSessionsStreamRequest.jsonOrThrow(_body, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
Expand Down Expand Up @@ -1435,10 +1438,12 @@ export class SessionsClient {
request: TrueForge.CreateTurnSessionsRequest,
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<TrueForge.GetTurnResponse>> {
const { assumeUser, ..._body } = request;
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
this._options?.headers,
mergeOnlyDefinedHeaders({ "assume-user": assumeUser }),
requestOptions?.headers,
);
const _response = await (this._options.fetcher ?? core.fetcher)({
Expand All @@ -1454,7 +1459,7 @@ export class SessionsClient {
requestType: "json",
body: mergeAdditionalBodyParameters(
{
...serializers.CreateTurnSessionsRequest.jsonOrThrow(request, {
...serializers.CreateTurnSessionsRequest.jsonOrThrow(_body, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ import type * as TrueForge from "../../../../index.js";
* }
*/
export interface CreateTurnSessionsRequest {
/** Service API key only: which user identity to assume. Currently only session-creator. */
assumeUser?: "session-creator";
Comment thread
thesujai marked this conversation as resolved.
Resolved
/** User messages for this turn. At least one is required. */
input: TrueForge.CreateTurnSessionsRequestInputItem[];
previousTurnId?: TrueForge.PreviousTurnIdInput;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ import type * as TrueForge from "../../../../index.js";
* }
*/
export interface CreateTurnSessionsStreamRequest {
/** Service API key only: which user identity to assume. Currently only session-creator. */
assumeUser?: "session-creator";
Comment thread
thesujai marked this conversation as resolved.
Resolved
/** User messages for this turn. At least one is required. */
input: TrueForge.CreateTurnSessionsStreamRequestInputItem[];
previousTurnId?: TrueForge.PreviousTurnIdInput;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,6 @@ export interface ListTurnsSessionsRequest {
limit?: number;
/** Opaque token from a previous response `next_page_token`. */
pageToken?: string;
/** Service API key only: which user identity to assume. Currently only session-creator. */
assumeUser?: "session-creator";
}
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { CreateTurnSessionsRequestInputItem } from "../../types/CreateTurnSessio

export const CreateTurnSessionsRequest: core.serialization.Schema<
serializers.CreateTurnSessionsRequest.Raw,
TrueForge.CreateTurnSessionsRequest
Omit<TrueForge.CreateTurnSessionsRequest, "assumeUser">
> = core.serialization.object({
input: core.serialization.list(CreateTurnSessionsRequestInputItem),
previousTurnId: core.serialization.property("previous_turn_id", PreviousTurnIdInput.optional()),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { CreateTurnSessionsStreamRequestInputItem } from "../../types/CreateTurn

export const CreateTurnSessionsStreamRequest: core.serialization.Schema<
serializers.CreateTurnSessionsStreamRequest.Raw,
TrueForge.CreateTurnSessionsStreamRequest
Omit<TrueForge.CreateTurnSessionsStreamRequest, "assumeUser">
> = core.serialization.object({
input: core.serialization.list(CreateTurnSessionsStreamRequestInputItem),
previousTurnId: core.serialization.property("previous_turn_id", PreviousTurnIdInput.optional()),
Expand Down
113 changes: 92 additions & 21 deletions packages/trueforge/src/apis/turns.ts
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ import { HTTPException } from 'hono/http-exception';
import { streamSSE } from 'hono/streaming';
import type { Logger } from 'winston';
import { z } from 'zod';
import { applyAssumeUserToContext, ASSUME_USER_HEADER } from '../auth/assumeUser';
import type { Authorizer } from '../auth/authorizer';
import {
requestContextFromCreatedBySubject,
Expand Down Expand Up @@ -1146,6 +1147,49 @@ function isSessionOwner({
return created_by_subject.subject_id === subject_id;
}

/**
* JWT context from auth middleware, or service-key + `assume-user` as the session creator.
* Callers load the session themselves after this returns.
*/
async function resolveTurnRequestContext<TTransaction>(params: {
c: Context;
sessions: Sessions<TTransaction>;
session_id: string;
resolveRequestContext: ResolveRequestContext;
}): Promise<RequestContext> {
const { c, sessions, session_id: sessionId, resolveRequestContext } = params;
const existing = c.get('request_context');
if (existing) {
return existing;
}
// Service key clears context; require assume-user so a JWT+header cannot take this path.
if (c.req.header(ASSUME_USER_HEADER)?.trim()) {
return applyAssumeUserToContext({
c,
resolveCreatedBy: async () => {
const session = await sessions.getById({ session_id: sessionId });
if (!session) {
throw new HTTPException(404, { message: `Session not found: ${sessionId}` });
}
return {
tenant_id: session.record.tenant_id,
created_by_subject: session.record.created_by_subject,
session_id: sessionId,
};
},
});
}
try {
return resolveRequestContext(c);
} catch (error) {
// Service key left context unset with no assume-user → 400, not a 500 from missing context.
if (error instanceof Error && error.message === 'RequestContext missing; auth middleware did not run') {
throw new HTTPException(400, { message: `Missing ${ASSUME_USER_HEADER} header`, cause: error });
}
throw error;
}
}

/** Request-reply path the owner serves for inbound turn events. */
const TURNS_SEND_EVENTS_PATH = 'turns/send-events';

Expand Down Expand Up @@ -1792,7 +1836,12 @@ export function createTurnsRouter<TTransaction>(deps: TurnsRouterDeps<TTransacti
const listTurnsHandler: RouteHandler<typeof listTurnsRoute> = async c => {
const { session_id: sessionId } = c.req.valid('param');
const query = c.req.valid('query');
const requestContext = deps.resolveRequestContext(c);
const requestContext = await resolveTurnRequestContext({
c,
sessions: deps.sessions,
Comment thread
thesujai marked this conversation as resolved.
Resolved
session_id: sessionId,
resolveRequestContext: deps.resolveRequestContext,
});
const session = await deps.sessions.get({
tenant_id: requestContext.tenant_id,
session_id: sessionId,
Expand Down Expand Up @@ -1971,34 +2020,56 @@ export function createTurnsRouter<TTransaction>(deps: TurnsRouterDeps<TTransacti
const createAndExecuteTurnHandler: RouteHandler<typeof createAndExecuteTurnRoute> = async c => {
const { session_id: sessionId } = c.req.valid('param');
const body = c.req.valid('json');
const requestContext = deps.resolveRequestContext(c);

const serviceAuth = !c.get('request_context') && Boolean(c.req.header(ASSUME_USER_HEADER)?.trim());
const requestContext = await resolveTurnRequestContext({
c,
sessions: deps.sessions,
session_id: sessionId,
resolveRequestContext: deps.resolveRequestContext,
});
const session = await deps.sessions.get({
tenant_id: requestContext.tenant_id,
session_id: sessionId,
});
if (!session) {
return c.json({ error: { message: `Session not found: ${sessionId}` } }, 404);
}
if (
!isSessionOwner({
subject_id: requestContext.subject.id,
created_by_subject: session.record.created_by_subject,
})
) {
return c.json({ error: { message: FORBIDDEN_CREATE_TURN } }, 403);
}

const agentUse = await referencedAgentForUse({
session,
requestContext,
agentStore: deps.resolveAgentStore(requestContext),
authorizer: deps.authorizer,
});
if (agentUse.type === 'rejected') {
return c.json({ error: { message: agentUse.message } }, agentUse.status);
let referencedAgent: AgentRecord | undefined;
if (serviceAuth) {
if (session.record.agent.type !== 'reference') {
throw new HTTPException(422, {
message: 'Service create-turn requires a session bound to a named agent (not an inline agent spec)',
});
}
const agent = await deps.resolveAgentStore(requestContext).getAgent({
tenant_id: requestContext.tenant_id,
id: session.record.agent.id,
});
if (!agent) {
return c.json({ error: { message: `Agent not found: ${session.record.agent.id}` } }, 422);
}
referencedAgent = agent;
} else {
if (
!isSessionOwner({
subject_id: requestContext.subject.id,
created_by_subject: session.record.created_by_subject,
})
) {
return c.json({ error: { message: FORBIDDEN_CREATE_TURN } }, 403);
}
const agentUse = await referencedAgentForUse({
session,
requestContext,
agentStore: deps.resolveAgentStore(requestContext),
authorizer: deps.authorizer,
});
if (agentUse.type === 'rejected') {
return c.json({ error: { message: agentUse.message } }, agentUse.status);
}
referencedAgent = agentUse.agent;
}
Comment thread
thesujai marked this conversation as resolved.
Resolved
const referencedAgent = agentUse.agent;

// x-tfg-skills / x-tfg-mcp / x-tfg-models on turns only when the session agent is inline.
const turnParams: BeginTurnExecutionParams<TTransaction> = {
Expand All @@ -2012,7 +2083,7 @@ export function createTurnsRouter<TTransaction>(deps: TurnsRouterDeps<TTransacti
session,
requestContext,
requestHeaders: c.req.header(),
...(referencedAgent !== undefined ? { runAsAgent: referencedAgent } : {}),
...(referencedAgent ? { runAsAgent: referencedAgent } : {}),
}),
};

Expand Down
Loading
Loading